Skip to content

Latest commit

 

History

History
511 lines (450 loc) · 48.4 KB

json-output.md

File metadata and controls

511 lines (450 loc) · 48.4 KB

JSON output

Four pharn commands can print JSON instead of text. Three of them print a versioned report; the fourth, pharn list --json, prints an unversioned inventory.

Command Output schemaVersion
pharn init --dry-run --json The install plan 1
pharn update --dry-run --json The update plan (--compact: short) 1
pharn status --json Version, drift and hook report 1
pharn list --json The installed capabilities none

--json implies --dry-run for init and update: pharn init --json, a bare pharn --json and pharn update --json print the same reports. --compact implies --json (and so --dry-run).

The stdout contract

For the three reports:

  • Exactly one JSON object on stdout, and nothing else: no banner, spinner, intro, outro or note. Diagnostics (the proxy notice, an unreadable upstream capability, a MIN_CLI warning) go to stderr.
  • On any failure stdout is empty, the reason is one plain line on stderr, and the exit code is 1. So pharn status --json | jq . either parses or receives nothing.
  • Exit codes. init --dry-run --json and update --dry-run --json exit 0 whatever the plan contains (there is no --strict for a preview). status --json exits as text mode does: --strict still prints the report and exits 1 on exactly the strict conditions that fail text mode, and the report's strict.failed says the same.
  • Escaped output. Characters a terminal would interpret (control characters, Unicode format characters, U+2028/U+2029) are written as \uXXXX escapes, so a cat of the output cannot move or hide text, and parsing returns the exact original string.
  • Capped free text. A reason or problem is cut at 300 characters, and an unknown capability's fields, a path from your tree, a carried config key or a settings.json key at 200, ending in … when cut.
  • Treat every string as data. Paths, capability names, reasons, hook commands and the models checker's words come from the fetched clone or your project files, not from pharn. The escaping is a statement about what a terminal can do with the output, not about whether the content is safe: an agent reading these fields must not follow instructions found in them.

pharn list --json keeps the first two rules (one object on stdout; on failure, stdout empty, the reason on stderr, exit 1) and differs in the others: see below.

Stability: schemaVersion 1

Each report carries its own schemaVersion, versioned independently of the others. All three are 1.

  • Match it exactly. Treat a value you do not know as a report you cannot read.
  • Additive changes stay within 1. A new key, or a new value of an enum-like field (as update's status gained ahead-of-main), does not bump it. Ignore keys you do not know, and treat an unknown update status as "do not apply".
  • In init and update, an optional key is absent when empty, never [] or null. Read such a key with a default (plan.orphans ?? []). The tables below mark each one absent when empty. status reports an empty or skipped part as null or [] instead.
  • A breaking change bumps it: removing, renaming or retyping a key. That is why some keys are constants today; they stay until a bump:
Report Key Always
update plan.abandonedLayout, plan.rootMigration null
update plan.models.replacedLegacyDefault false
update plan.models.conversion null
status layout.recorded (and layout.upstream when not null) "pharn"
status models.conversionNeeded false (verdict is never old-format)

pharn no longer moves an install between layouts or retires a pre-7.0 root footprint (both removed in v0.21.0), and no longer converts the pre-0.7.0 models format; the keys above stay for schemaVersion 1. This rule is a documented contract: the test suite pins each report's key list, and pharn enforces nothing at run time.

Types used below

Name Shape
HookEntry {event, matcher, command, args}: strings, args a string array (empty unless the hook is in exec form)
HookReplace {upstream: HookEntry, existing: [{file, entry: HookEntry}]}: a missing hook your project wires in another spelling (replace, not add)
Removal {role, name, reason, dir, present, backups}: reason dropped-unselected or dropped-gone; dir the capability directory a real run would delete; present whether anything is there; backups the files in it copied to pharn/.backup/<timestamp>/ first
IgnoreEdit {action, entries} with action create or append and entries the lines added, or {action: "refused", reason, entries} with reason symlink, not-a-file or unreadable and the lines to add yourself
Absent {surface, path}: a declared surface the fetched clone ships no file for; surface is commands, hooks, trusted-doc, license, features-readme, contracts, core or floor
Unknown {role, name, subtree, reason}: an upstream capability this pharn cannot read, skipped
Orphan {path, state} with state unchanged, edited or unreadable (then also reason): a recorded file upstream no longer ships, still on disk
Hooks {status, missing: HookEntry[], localOnly: HookEntry[], file, reason} plus replace: HookReplace[] (absent when empty). status is match, local-only, missing, no-upstream, project-absent or unreadable; file/reason name an unreadable settings file, else null

pharn init --dry-run --json

The plan pharn init would carry out, from the same planner as the text preview; it writes nothing. See pharn init for what the plan means.

Key Type Notes
schemaVersion 1
command, dryRun, status "init", true, "planned" Constants.
channel "latest" or "main" main under --ref main.
source {kind, tag} kind release (with its tag) or main (tag null).
commit string or null The commit the plan was made from.
skillsVersion string The version upstream ships.
layout "pharn"
archetypes string array The archetypes the install uses (ssr, backend, spa, lib).
archetypeSource "detected" or "flag" flag under --archetype.
detectedArchetypes string array or null With flag: what detection found and did not use. null otherwise.
archetypeEvidence {archetype, source, value}[] Detection's trigger per archetype it found: source dependency or devDependency (value the package name), path (the first triggering path, a directory ending in /) or none (lib, value null). Always detection's, also under flag.
detectionTruncated true Absent when empty. Present only when detection's scan stopped at a bound (50,000 entries, 24 directories deep) before its result was settled.
capabilities.selected {role, name, matched}[] matched is "universal", "manual" or the archetypes that selected it.
capabilities.skipped {role, name, reason}[] Capabilities upstream ships that this install leaves out.
capabilities.carried {manual, kept, dropped} role:name keys from the config a re-install replaces: manual entries (pharn add) it keeps, kept entries this pharn cannot read (kept verbatim), dropped manual entries upstream no longer ships. Empty on a first install.
capabilities.removals Removal[] Absent when empty. The capability directories a re-install would delete.
unknownCapabilities Unknown[]
targets {rel, action, label}[] Every file the install writes, plus pharn.config.json, sorted. action create or overwrite. label modified, unrecorded or unverifiable (backed up first), rewritten (an existing pharn.config.json, always backed up), else null.
backups string array The files copied to pharn/.backup/<timestamp>/ first.
counts {create, overwrite, backup} Numbers.
yesWouldProceed boolean Whether pharn init --yes would install now: true only when nothing would be overwritten.
settings.preserved boolean Whether .claude/settings.json exists and is kept.
hooks Hooks or null The hook comparison against a preserved settings.json. null when there is none to preserve.
settingsHooks {status: "ok", hooks: HookEntry[], otherKeys, skipped} or {status: "unreadable", reason} Absent when empty. Present only when the install would write .claude/settings.json from upstream: what that file wires, its other top-level keys (sorted) and the number of hook entries pharn could not read.
absentUpstream Absent[] Absent when empty.
models {outcome, reasons} outcome copy, none (upstream ships no block) or rejected (with reasons). The block itself is not included.
config.carriedKeys string array Your own config keys the install keeps, by name only.
gitignore IgnoreEdit Absent when empty. Present only when the install would change .gitignore, or would have to leave it alone.
prettierignore IgnoreEdit Absent when empty. The same for .prettierignore, in a project that uses Prettier.

A non-null label in targets means the file is in backups; the overwrite prompt shows modified, unrecorded and unverifiable as (edited), (no pharn record) and (differs from upstream).

Example

A fresh project with next in its dependencies:

pharn init --dry-run --json
{
  "schemaVersion": 1,
  "command": "init",
  "dryRun": true,
  "status": "planned",
  "channel": "latest",
  "source": { "kind": "release", "tag": "v7.22.0" },
  "commit": "9422b97f9bcef022d240822024e75a1a49c6e278",
  "skillsVersion": "7.22.0",
  "layout": "pharn",
  "archetypes": ["ssr"],
  "archetypeSource": "detected",
  "detectedArchetypes": null,
  "archetypeEvidence": [
    { "archetype": "ssr", "source": "dependency", "value": "next" }
  ],
  "capabilities": {
    "selected": [
      { "role": "griller", "name": "a11y", "matched": ["ssr"] },
      { "role": "griller", "name": "architecture", "matched": "universal" }
    ],
    "skipped": [],
    "carried": { "manual": [], "kept": [], "dropped": [] }
  },
  "unknownCapabilities": [],
  "targets": [
    {
      "rel": ".claude/agents/pharn-review-lens.md",
      "action": "create",
      "label": null
    },
    {
      "rel": ".claude/commands/pharn-plan.md",
      "action": "create",
      "label": null
    },
    { "rel": "pharn.config.json", "action": "create", "label": null },
    { "rel": "pharn/CONSTITUTION.md", "action": "create", "label": null }
  ],
  "backups": [],
  "counts": { "create": 614, "overwrite": 0, "backup": 0 },
  "yesWouldProceed": true,
  "settings": { "preserved": false },
  "hooks": null,
  "settingsHooks": {
    "status": "ok",
    "hooks": [
      {
        "event": "PreToolUse",
        "matcher": "Write|Edit|MultiEdit|NotebookEdit",
        "command": "node \"${CLAUDE_PROJECT_DIR}\"/.claude/hooks/protect-trusted-paths.cjs",
        "args": []
      }
    ],
    "otherKeys": [],
    "skipped": 0
  },
  "models": { "outcome": "copy", "reasons": [] },
  "config": { "carriedKeys": [] },
  "gitignore": {
    "action": "create",
    "entries": ["pharn/.run/", "pharn/.backup/"]
  }
}

Trimmed: capabilities.selected shows 2 of 35 entries, targets 4 of 614 and settingsHooks.hooks 1 of 3.

pharn update --dry-run --json

The plan pharn update would carry out; it writes nothing. It composes with --force and --ref; --yes is accepted and does nothing. See pharn update for what the plan means.

The outcome is status:

status Meaning plan
planned A real run would proceed. object
up-to-date The plan changes nothing: a real run would ask nothing and write nothing (it may still keep an edit of yours). null
ahead-of-release The install is newer than the newest verified release (--ref latest); nothing changes without --force. null
ahead-of-main The install is newer than pharn-oss main; nothing changes without --force. null
Key Type Notes
schemaVersion 1
command, dryRun "update", true Constants.
compact true Present only under --compact, on every status.
status string The table above.
force boolean Whether --force was passed.
channel "latest" or "main" The channel this run used.
channelChange {from, to} or null Set when --ref would switch the recorded channel.
source {kind, tag} kind release (with its tag) or main (tag null).
version {installed, latest, recorded, withheld, pending} installed: recorded now; latest: what upstream ships. With a plan: recorded is the version a real run would record, withheld says skipped files would hold it back, pending the pendingSkillsVersion a real run would record (else null). The last three are null without a plan.
archetypes string array The recorded archetypes.
plan object or null Set only when status is planned. Its keys follow.
plan.layout "pharn" abandonedLayout and rootMigration beside it are always null.
plan.featuresReadmeRelocation boolean Whether a copy of the boundary contract would be left at the project root.
plan.capabilities {count, changes} The count after the update and every membership change as {role, name, source, reason}: source auto, manual or null; reason added, dropped-unselected, dropped-gone, kept-manual or kept-frozen.
plan.capabilities.removals Removal[] Absent when empty. The directories a real run would delete.
plan.files {rel, action, label, backup, forced}[] Every installed file. action write, noop or skip; label restored, updated, ok, or a skip reason (modified, unrecorded, unverifiable, unreadable, held); forced: --force made it a write; backup: copied first.
plan.filesOmitted {action: "noop", count} Present only under --compact: what files leaves out. count equals counts.ok.
plan.writes string array The files a real run would write, in install order.
plan.backups string array The files copied to pharn/.backup/<timestamp>/ first (pharn.config.json too when --force replaces your models block).
plan.skipped {label, rels}[] Skipped files grouped by reason, most actionable first.
plan.counts {updated, restored, ok, forced, skipped} Totals; never filtered by --compact.
plan.executableUnit {blocking, held, missing} Absent when empty. The executable-unit hold: blocking the skipped unit files as {rel, label}, held the unit files not written because of them, missing (absent when empty) the held files not on disk.
plan.models {outcome, label, replacedLegacyDefault, backup, conversion, problems, upstreamReasons} outcome restored, updated, ok, kept, forced, upstream-absent or upstream-invalid; label the skip label when the block is yours, else null; backup: pharn.config.json copied first. The block itself is not included.
plan.hooks Hooks The same comparison as status --json. update never writes your settings files.
plan.absentUpstream Absent[] Absent when empty.
plan.frozenCapabilities string array role:name of capabilities upstream ships that this pharn cannot read, kept as they are.
plan.unknownCapabilities Unknown[]
plan.recordsNote string or null Why pharn.records.json could not be used (every difference is then unverifiable).
plan.orphans Orphan[] Absent when empty. Never filtered by --compact.
plan.gitignore, plan.prettierignore IgnoreEdit Absent when empty. Present only when a real run would change the file, or would have to leave it alone.

--compact

plan.files lists every installed file, most of them noop on a large install. pharn update --dry-run --json --compact leaves out exactly the noop entries, adds compact: true and plan.filesOmitted, and changes nothing else: files.length + filesOmitted.count is the installed-file total. The default report has neither key and always holds the full list.

Example

The project from the init example after pharn init --yes, with one installed file edited (.claude/commands/pharn-plan.md) and one deleted (pharn/CONSTITUTION.md):

pharn update --dry-run --json
{
  "schemaVersion": 1,
  "command": "update",
  "dryRun": true,
  "status": "planned",
  "force": false,
  "channel": "latest",
  "channelChange": null,
  "source": { "kind": "release", "tag": "v7.22.0" },
  "version": {
    "installed": "7.22.0",
    "latest": "7.22.0",
    "recorded": "7.22.0",
    "withheld": true,
    "pending": null
  },
  "archetypes": ["ssr"],
  "plan": {
    "layout": "pharn",
    "abandonedLayout": null,
    "featuresReadmeRelocation": false,
    "rootMigration": null,
    "capabilities": { "count": 35, "changes": [] },
    "files": [
      {
        "rel": ".claude/agents/pharn-review-lens.md",
        "action": "noop",
        "label": "ok",
        "backup": false,
        "forced": false
      },
      {
        "rel": ".claude/commands/pharn-plan.md",
        "action": "skip",
        "label": "modified",
        "backup": false,
        "forced": false
      },
      {
        "rel": "pharn/CONSTITUTION.md",
        "action": "write",
        "label": "restored",
        "backup": false,
        "forced": false
      }
    ],
    "writes": ["pharn/CONSTITUTION.md"],
    "backups": [],
    "skipped": [
      { "label": "modified", "rels": [".claude/commands/pharn-plan.md"] }
    ],
    "counts": {
      "updated": 0,
      "restored": 1,
      "ok": 611,
      "forced": 0,
      "skipped": 1
    },
    "models": {
      "outcome": "ok",
      "label": null,
      "replacedLegacyDefault": false,
      "backup": false,
      "conversion": null,
      "problems": [],
      "upstreamReasons": []
    },
    "hooks": {
      "status": "match",
      "missing": [],
      "localOnly": [],
      "file": null,
      "reason": null
    },
    "frozenCapabilities": [],
    "unknownCapabilities": [],
    "recordsNote": null
  }
}

Trimmed: plan.files shows the first entry and the two that are not noop, of 613. withheld is true because the skipped edit holds the version back.

pharn status --json

The version, drift and hook report, on the default path and under --no-drift. See pharn status for what each part means.

Key Type Notes
schemaVersion 1
node {floor, running, status} The floor (24.2.0), the running Node (null when it reports none) and status ok, below or unparseable. Never a --strict input.
version {installed, latest, channel, source, ahead, outdated} The installed and latest skills versions, channel latest or main, source {kind, tag} as in the other reports, ahead (newer than the source it follows) and outdated.
archetypes string array The recorded archetypes.
capabilities.count number The list itself is pharn list --json.
layout {recorded, upstream} Both "pharn"; upstream is null under --no-drift.
drift object or null {modified, missing, unreadable, okCount, absentUpstream}: modified and missing path arrays, unreadable as {rel, reason}[], okCount a number, absentUpstream an Absent[] (always present here). null under --no-drift.
hooks Hooks or null null under --no-drift.
models object or null null without a models block; else {conversionNeeded, verdict, stages, reds}: verdict valid, no-stages or invalid; stages {stage, model, effort, viaDefault}[] when valid, else null; reds {kind, detail}[] when invalid, else null.
unknownCapabilities Unknown[] or null null under --no-drift.
orphans Orphan[] or null null under --no-drift or without a usable pharn.records.json. Never a --strict input.
prettierignore IgnoreEdit or null What pharn update would do to .prettierignore; null when there is nothing to say or no usable pharn.records.json. Answered under --no-drift too. Never a --strict input.
strict {enabled, failed} --strict passed, and whether it exits 1 (the strict conditions).

Unlike the other two reports, status --json reports an empty or skipped part as null or [] rather than leaving the key out; only hooks.replace is absent when empty.

Example

The same project as the update example:

pharn status --json
{
  "schemaVersion": 1,
  "node": { "floor": "24.2.0", "running": "24.13.1", "status": "ok" },
  "version": {
    "installed": "7.22.0",
    "latest": "7.22.0",
    "channel": "latest",
    "source": { "kind": "release", "tag": "v7.22.0" },
    "ahead": false,
    "outdated": false
  },
  "archetypes": ["ssr"],
  "capabilities": { "count": 35 },
  "layout": { "recorded": "pharn", "upstream": "pharn" },
  "drift": {
    "modified": [".claude/commands/pharn-plan.md"],
    "missing": ["pharn/CONSTITUTION.md"],
    "unreadable": [],
    "okCount": 611,
    "absentUpstream": []
  },
  "hooks": {
    "status": "match",
    "missing": [],
    "localOnly": [],
    "file": null,
    "reason": null
  },
  "models": {
    "conversionNeeded": false,
    "verdict": "valid",
    "stages": [
      {
        "stage": "default",
        "model": "sonnet",
        "effort": "high",
        "viaDefault": false
      },
      {
        "stage": "spec",
        "model": "opus",
        "effort": "high",
        "viaDefault": false
      },
      {
        "stage": "triage",
        "model": "sonnet",
        "effort": "high",
        "viaDefault": true
      }
    ],
    "reds": null
  },
  "unknownCapabilities": [],
  "orphans": [],
  "prettierignore": null,
  "strict": { "enabled": false, "failed": false }
}

Trimmed: models.stages shows 3 of 14 rows.

pharn list --json

The installed archetypes and capabilities, read from pharn.config.json alone: no download, no lock. See pharn list.

It is unversioned. It has no schemaVersion and is not covered by the stability rule above. It is printed with plain JSON.stringify, without the \uXXXX escaping of the reports: every value it prints passed an allowlist when the config was loaded (skillsVersion a version, the archetypes and roles from fixed sets, a capability name one lowercase, hyphen-separated segment, source auto or manual), so none can hold a character a terminal would interpret.

Key Type Notes
mode "archetype" The only mode.
skillsVersion string The installed content version.
archetypes string array The recorded archetypes.
capabilities {name, role, source}[] In config order. role griller or lens. source is absent when the config does not record it (provenance not yet known), never defaulted.

Example

The same project:

pharn list --json
{
  "mode": "archetype",
  "skillsVersion": "7.22.0",
  "archetypes": ["ssr"],
  "capabilities": [
    { "name": "a11y", "role": "griller", "source": "auto" },
    { "name": "architecture", "role": "griller", "source": "auto" },
    { "name": "copy-paste-drift", "role": "lens", "source": "auto" }
  ]
}

Trimmed: capabilities shows 3 of 35 entries.

How the examples were made

Each example is real output of the CLI built from this repository (npm run build; pharn below is node <checkout>/dist/index.js), run on 2026-11-17 against the pharn-oss v7.22.0 release, in a new project whose package.json lists next in its dependencies, after git init:

pharn init --dry-run --json   # the init example, before installing
pharn init --yes
# then: append a line to .claude/commands/pharn-plan.md and delete pharn/CONSTITUTION.md
pharn update --dry-run --json # the update example
pharn status --json           # the status example
pharn list --json             # the list example

The output was re-indented to fit this page; the trims are named under each example, and every key and value shown is as printed. A newer pharn-oss changes the versions, the commit and the counts.