Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ Releases 0.4.0 and older are in [CHANGELOG-ARCHIVE.md](CHANGELOG-ARCHIVE.md).
### Changed

- **`pharn --help` no longer says each option belongs to one command.** `--json`, `--yes`, `--ref` and `--dry-run` are taken by several, as the lines below the header already showed. The header now reads "Options (each names the commands that take it; any other command refuses it):".
- **`pharn status --help` now names every condition `--strict` fails on.** The `--strict` line said "exit 1 on any outdated/modified/missing file"; it now reads "exit 1 on an outdated install, a modified, missing or unreadable file, a surface upstream no longer ships, or an unwired hook (under --no-drift, only outdated is checked)", on both `pharn --help` and `pharn status --help`. What `--strict` checks is unchanged. The one full list, including what is never a `--strict` input (orphans, the `PRETTIER`, `NODE` and `MODELS` notes, a hook wired only in `settings.local.json`), is the new "Strict conditions" section of `docs/commands/status.md`, and `docs/README.md`, the troubleshooting exit-code table, the `status --json` summary and the JSON output reference link to it.

## [0.21.0] — 2026-11-17

Expand Down
2 changes: 1 addition & 1 deletion docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ The CLI version (`pharn --version`) and the content version it installs (`skills
- [uninstall](commands/uninstall.md) — remove PHARN, deleting only the files `pharn` wrote and you did not change
- [update](commands/update.md) — re-fetch installed capabilities at the latest skills version
- [list](commands/list.md) — list installed archetypes + capabilities
- [status](commands/status.md) — read-only version + local-drift check; `--strict` exits 1 on any outdated/modified/missing/unreadable file, and neither `status` nor `list` is ever blocked by another `pharn` run's lock
- [status](commands/status.md) — read-only version + local-drift check; `--strict` exits 1 on an outdated install, a modified, missing or unreadable file, a surface upstream no longer ships, or an unwired hook ([the full list](commands/status.md#strict-conditions)), and neither `status` nor `list` is ever blocked by another `pharn` run's lock

## Reference

Expand Down
4 changes: 2 additions & 2 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -283,8 +283,8 @@ Strictly read-only.
not read the records; only `update` can tell an upgrade from a skip.
- **Hooks** (`lib/hook-wiring.ts`): upstream's hook entries against the project's `settings.json` ∪
`settings.local.json`.
- A recorded layout that differs from the clone's prints a `LAYOUT` note instead of drift.
- `--no-drift` skips the clone. `--strict` exits 1 on an outdated, modified, missing, unreadable or
not-shipped-upstream finding, a layout mismatch, or an unwired hook. Orphans and the `MODELS` and `PRETTIER` notes
not-shipped-upstream finding, or an unwired hook (`strictFails`; the user-facing list is
[`status`'s Strict conditions](commands/status.md#strict-conditions)). Orphans and the `MODELS` and `PRETTIER` notes
are advisory.
- `--json` prints one object (`schemaVersion: 1`) through `serializeStatusReport`.
54 changes: 47 additions & 7 deletions docs/commands/status.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ from upstream?
```bash
pharn status
pharn status --no-drift # version check only (skips the clone)
pharn status --strict # exit 1 if outdated, differing, missing, unreadable, not shipped upstream, or a hook is unwired (for CI)
pharn status --strict # exit 1 on any strict condition (for CI): see "Strict conditions" below
pharn status --json # one machine-readable report on stdout (for scripts, CI and agents)
```

Expand Down Expand Up @@ -149,8 +149,9 @@ current and intact.

`pharn status --json` prints the same report as **one JSON object** on stdout and nothing else, on the
default path and under `--no-drift`. Exit codes match text mode: `--strict` still prints the report, and
its `strict.failed` says whether it exits 1. Its keys, the `schemaVersion` 1 stability rule and a real
example are in the [JSON output reference](../reference/json-output.md#status).
its `strict.failed` says whether it exits 1, on exactly the [strict conditions](#strict-conditions). Its
keys, the `schemaVersion` 1 stability rule and a real example are in the
[JSON output reference](../reference/json-output.md#status).

## What is intentionally excluded

Expand All @@ -162,7 +163,8 @@ project. The `HOOKS` section works like this:

- **Missing.** It names every hook the upstream `settings.json` wires that neither project file does.
Extra hooks of your own never count, and matching is textual. `--strict` exits `1` while any is
missing, or while a project settings file cannot be read.
missing, while a project settings file cannot be read, or while neither project settings file
exists (see [Strict conditions](#strict-conditions)).
- **Replace, not add.** If a project file already wires the same `.claude/hooks/` script under the
same event and matcher in another spelling (say, the relative `node .claude/hooks/x.cjs` where
upstream anchors it on `${CLAUDE_PROJECT_DIR}`), the hook is listed under `REPLACE`, with your
Expand All @@ -185,9 +187,47 @@ project. The `HOOKS` section works like this:
## Exit code

Exits `0` by default, even when drift or an available update is found (it is a report) — including when
a path is unreadable. Pass `--strict` to exit `1` whenever anything is outdated, differing, missing,
unreadable, or not shipped upstream, or an upstream hook is wired in
neither `.claude/settings.json` nor `.claude/settings.local.json` — useful as a CI gate.
a path is unreadable. Pass `--strict` to exit `1` on any of the [strict conditions](#strict-conditions)
below — useful as a CI gate.

### Strict conditions

This is the one list of what fails `--strict`. `pharn status --help`, the
[exit-code table](../troubleshooting.md#exit-codes) and the `--json` report's `strict.failed` mean
exactly this. `--strict` exits `1` when any of these holds:

1. **Outdated.** Your `skillsVersion` differs from the `SKILLS_VERSION` of the source the install
follows, and is not ahead of it. An install **ahead** of its source is not outdated (see
[Behavior](#behavior)).
2. **Differs.** A PHARN-owned file on disk whose content differs from upstream's (line endings in text
files are ignored).
3. **Missing.** A file your recorded capabilities or the fixed product surfaces should contribute is not
on disk.
4. **Unreadable.** An expected path that cannot be compared: a symlink, a file under a symlinked parent,
a directory or another non-regular file, an unreadable file.
5. **Not shipped upstream.** A product surface the install declares for which the fetched clone ships
no file at all.
6. **Unwired hook.** The upstream `.claude/settings.json` wires hooks (when it wires none, this
condition never holds), and one of:
- one of those hooks is wired in neither `.claude/settings.json` nor `.claude/settings.local.json`;
- either of those two files cannot be read (it could wire anything, so the answer is unknown);
- neither file exists.

Under `--no-drift` only condition 1 is checked: there is no clone to compare conditions 2 to 6 against.

These are reported and **never** fail `--strict`:

- [orphaned files](#orphaned-files), in any group;
- the [`PRETTIER`](#prettier) note;
- the `NODE` mismatch (a Node older than the floor, or one whose version cannot be read);
- the `MODELS` note's REDs (a `models` block pharn-oss's rules reject);
- a hook wired **only** in `.claude/settings.local.json`, and extra hooks of your own;
- an install ahead of the source it follows, and the channel or release line;
- an installed capability this `pharn` cannot read in the fetched clone (an unknown `role` or `applies`,
or a name that fails the allowlist): it is warned about as SKIPPED and left out of the comparison;
- the layout: there is no `LAYOUT` note. An install recorded at the removed `flat` layout is refused
before any report (exit `1` with or without `--strict`, [Behavior](#behavior) step 7), a failure and
not a finding.

`--strict` governs **findings**, not failures. `status` still exits `1` without it when it cannot
produce a report at all: no `pharn.config.json` (or a pre-archetype one), a clone it cannot fetch, or
Expand Down
5 changes: 3 additions & 2 deletions docs/reference/json-output.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,8 @@ For the three reports:
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 inputs that fail text mode, and the report's
still prints the report and exits `1` on exactly the
[strict conditions](../commands/status.md#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
Expand Down Expand Up @@ -372,7 +373,7 @@ The version, drift and hook report, on the default path and under `--no-drift`.
| `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`. |
| `strict` | `{enabled, failed}` | `--strict` passed, and whether it exits `1` (the [strict conditions](../commands/status.md#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.
Expand Down
2 changes: 1 addition & 1 deletion docs/troubleshooting.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@
| Unknown option, an option the command does not take, or an unexpected extra argument | 1 |
| A value on an on/off option (`--json=false`), or `--ref` / `--archetype` given twice | 1 |
| `add` / `update` / `remove` / `list` / `status` with no `pharn.config.json` (or a pre-archetype config) | 1 |
| `status --strict` found anything outdated, modified, missing or unreadable | 1 |
| `status --strict` found a [strict condition](commands/status.md#strict-conditions) | 1 |
| `init` or `update` run without an interactive terminal (and `add`/`remove` with no name) | 1 |
| `init --yes` in a project where a file it would write already exists (nothing written) | 1 |
| `init --dry-run` printed its plan (nothing was written) | 0 |
Expand Down
6 changes: 4 additions & 2 deletions src/commands/status.ts
Original file line number Diff line number Diff line change
Expand Up @@ -60,8 +60,10 @@ import type { InstalledCapability, PharnConfig } from '../types.js';
* section)? Never writes — fixing is `pharn update` / `pharn add`.
*
* Default clones once for both sections; `--no-drift` checks the version only.
* `--strict` exits 1 on anything outdated, modified or missing, or an unwired
* upstream hook. The work is done once into ONE
* `--strict` exits 1 on an outdated install, a modified, missing or unreadable
* file, a declared surface upstream no longer ships, or an unwired upstream
* hook — `strictFails` (lib/status-report.ts) is the one predicate, and
* docs/commands/status.md lists it. The work is done once into ONE
* `StatusReport` (lib/status-report.ts): `--json` prints it, the text notes are
* rendered from it, and both read `--strict`'s verdict off it. `--json` emits
* ONE object on stdout and nothing else; diagnostics and failures go to
Expand Down
6 changes: 5 additions & 1 deletion src/lib/cli-args.ts
Original file line number Diff line number Diff line change
Expand Up @@ -159,7 +159,11 @@ const OPTIONS: readonly OptionSpec[] = [
uses: [
{
commands: ['status'],
text: ['exit 1 on any outdated/modified/missing file'],
text: [
'exit 1 on an outdated install, a modified, missing or unreadable',
'file, a surface upstream no longer ships, or an unwired hook',
'(under --no-drift, only outdated is checked)',
],
},
],
},
Expand Down
19 changes: 18 additions & 1 deletion tests/cli-args.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -620,10 +620,27 @@ describe('parseCliArgs: --version and --help', () => {

it('describes an option on its command page without the command prefix', () => {
const page = printed(['status', '--help']);
expect(page).toMatch(/--strict +exit 1 on any outdated/);
expect(page).toMatch(/--strict +exit 1 on an outdated install/);
expect(page).not.toMatch(/status: /);
});

it('names every condition `strictFails` checks on the `--strict` line', () => {
// strictFails (lib/status-report.ts): outdated, modified/missing/unreadable
// files, a surface upstream no longer ships, an unwired hook.
const help = printed(['status', '--help']).replace(/\s+/g, ' ');
for (const condition of [
'outdated',
'modified',
'missing',
'unreadable',
'upstream no longer ships',
'unwired hook',
'under --no-drift, only outdated',
]) {
expect(help, condition).toContain(condition);
}
});

it('shows only the use of a shared option that belongs to the command', () => {
const page = printed(['list', '--help']);
expect(page).toMatch(/--json +emit the inventory as JSON/);
Expand Down
Loading