@inventarch/cli 0.0.0-stage → 1.0.0

package/dist/args.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The consumer argument grammar: docs/specs/consumer-cli-contract/README.md §2.0.
+ *
+ * `--flag value` and `--flag=value`, boolean flags, a bare `--` separator, repeatable flags and repeatable
+ * positionals. A command declares its shape in a table and the parser enforces it, so no handler reads a flag
+ * name of its own. Every refusal here is IA-CLI-USAGE at exit 2 (§3) and happens before any workspace,
+ * installation state, cache or network read.
+ */
+export declare class UsageError extends Error {
+    readonly code = "IA-CLI-USAGE";
+    constructor(message: string);
+}
+export interface OptionSpec {
+    readonly name: string;
+    readonly kind: 'boolean' | 'value';
+    /** One-letter alias, matched as an exact token; bundling such as `-qy` is not admitted. */
+    readonly short?: string;
+    readonly repeatable?: boolean;
+    /** A closed value set. A value outside it is a usage error, not a later refusal. */
+    readonly values?: readonly string[];
+    readonly integer?: {
+        readonly min: number;
+        readonly max?: number;
+    };
+    /** How the value is spelled in help; defaults to the value set, or `<value>`. */
+    readonly placeholder?: string;
+    readonly required?: boolean;
+    /** Names that may not appear alongside this one, in either order. */
+    readonly conflicts?: readonly string[];
+    /** §2.2: `--schema` and `--example` are meaningless without the word they describe. */
+    readonly needsPositional?: boolean;
+    /** §2.8: `--requests` carries the set the positionals would have carried. */
+    readonly excludesPositionals?: boolean;
+    /** §2.1 rejects the common `--root` for `ia init`; the reason is stated rather than spelled as "unknown". */
+    readonly refuse?: string;
+    readonly summary: string;
+}
+export interface PositionalSpec {
+    readonly name: string;
+    readonly min: number;
+    /** `Number.POSITIVE_INFINITY` for a repeatable positional. */
+    readonly max: number;
+}
+export interface Grammar {
+    readonly options: readonly OptionSpec[];
+    readonly positionals: PositionalSpec;
+}
+export interface Arguments {
+    readonly positionals: readonly string[];
+    /** True when the boolean flag was supplied. */
+    readonly flag: (name: string) => boolean;
+    /** The single value of a non-repeatable value flag. */
+    readonly value: (name: string) => string | undefined;
+    /** Every occurrence of a repeatable value flag, in the order supplied. */
+    readonly list: (name: string) => readonly string[];
+    readonly integer: (name: string, fallback: number) => number;
+}
+export declare const positionals: (name: string, min: number, max: number) => PositionalSpec;
+export declare const none: PositionalSpec;
+/** §2.0. Pure: the same argv and grammar always produce the same result or the same refusal. */
+export declare function parseArguments(argv: readonly string[], grammar: Grammar): Arguments;
+//# sourceMappingURL=args.d.ts.map

package/dist/args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../src/args.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,qBAAa,UAAW,SAAQ,KAAK;IACnC,QAAQ,CAAC,IAAI,kBAAkB;gBACnB,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC;IACnC,2FAA2F;IAC3F,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,oFAAoF;IACpF,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACnE,iFAAiF;IACjF,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,qEAAqE;IACrE,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,uFAAuF;IACvF,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC,6EAA6E;IAC7E,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IACvC,6GAA6G;IAC7G,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AACD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,8DAA8D;IAC9D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AACD,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;IACxC,QAAQ,CAAC,WAAW,EAAE,cAAc,CAAC;CACtC;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACzC,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IACrD,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,SAAS,MAAM,EAAE,CAAC;IACnD,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;CAC9D;AAGD,eAAO,MAAM,WAAW,GAAI,MAAM,MAAM,EAAE,KAAK,MAAM,EAAE,KAAK,MAAM,KAAG,cAAsC,CAAC;AAC5G,eAAO,MAAM,IAAI,gBAAiB,CAAC;AAInC,gGAAgG;AAChG,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,OAAO,GAAG,SAAS,CA+FnF"}

package/dist/args.js

@@ -0,0 +1,117 @@
+/**
+ * The consumer argument grammar: docs/specs/consumer-cli-contract/README.md §2.0.
+ *
+ * `--flag value` and `--flag=value`, boolean flags, a bare `--` separator, repeatable flags and repeatable
+ * positionals. A command declares its shape in a table and the parser enforces it, so no handler reads a flag
+ * name of its own. Every refusal here is IA-CLI-USAGE at exit 2 (§3) and happens before any workspace,
+ * installation state, cache or network read.
+ */
+export class UsageError extends Error {
+    code = 'IA-CLI-USAGE';
+    constructor(message) {
+        super(message);
+        this.name = 'UsageError';
+    }
+}
+const NO_POSITIONALS = { name: 'argument', min: 0, max: 0 };
+export const positionals = (name, min, max) => ({ name, min, max });
+export const none = NO_POSITIONALS;
+const label = (option) => `--${option.name}`;
+/** §2.0. Pure: the same argv and grammar always produce the same result or the same refusal. */
+export function parseArguments(argv, grammar) {
+    const byToken = new Map();
+    for (const option of grammar.options) {
+        byToken.set(`--${option.name}`, option);
+        if (option.short !== undefined)
+            byToken.set(`-${option.short}`, option);
+    }
+    const values = new Map(), flags = new Set(), rest = [];
+    let separated = false;
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (!separated && token === '--') {
+            separated = true;
+            continue;
+        }
+        if (separated || !token.startsWith('-') || token === '-') {
+            rest.push(token);
+            continue;
+        }
+        const split = token.indexOf('='), key = split === -1 ? token : token.slice(0, split);
+        const option = byToken.get(key);
+        if (option === undefined)
+            throw new UsageError(`Unknown option ${key}`);
+        if (option.refuse !== undefined)
+            throw new UsageError(option.refuse);
+        if (option.kind === 'boolean') {
+            if (split !== -1)
+                throw new UsageError(`Option ${label(option)} does not take a value`);
+            if (flags.has(option.name))
+                throw new UsageError(`Duplicate option ${label(option)}`);
+            flags.add(option.name);
+            continue;
+        }
+        // A separate token is taken as the value unless it is itself a declared option, so `--search -x` works and
+        // `--severity --json` refuses instead of silently swallowing the next flag. `--flag=value` escapes both.
+        const next = argv[index + 1];
+        const supplied = split === -1 ? (next !== undefined && byToken.has(next) ? undefined : next) : token.slice(split + 1);
+        if (supplied === undefined || supplied === '')
+            throw new UsageError(`Option ${label(option)} requires a value`);
+        if (split === -1)
+            index += 1;
+        const seen = values.get(option.name);
+        if (seen !== undefined && option.repeatable !== true)
+            throw new UsageError(`Duplicate option ${label(option)}`);
+        if (seen === undefined)
+            values.set(option.name, [supplied]);
+        else
+            seen.push(supplied);
+    }
+    for (const option of grammar.options) {
+        const present = option.kind === 'boolean' ? flags.has(option.name) : values.has(option.name);
+        if (!present) {
+            if (option.required === true)
+                throw new UsageError(`Option ${label(option)} is required`);
+            continue;
+        }
+        for (const other of option.conflicts ?? []) {
+            const conflicting = flags.has(other) || values.has(other);
+            if (conflicting)
+                throw new UsageError(`Options ${label(option)} and --${other} are mutually exclusive`);
+        }
+        if (option.needsPositional === true && rest.length === 0)
+            throw new UsageError(`Option ${label(option)} requires <${grammar.positionals.name}>`);
+        if (option.excludesPositionals === true && rest.length > 0)
+            throw new UsageError(`Option ${label(option)} and <${grammar.positionals.name}> are mutually exclusive`);
+        for (const value of values.get(option.name) ?? []) {
+            if (option.values !== undefined && !option.values.includes(value))
+                throw new UsageError(`Option ${label(option)} accepts ${option.values.join(', ')}; got ${value}`);
+            if (option.integer !== undefined) {
+                const parsed = Number(value), { min, max } = option.integer;
+                if (!/^-?\d+$/.test(value) ||
+                    !Number.isSafeInteger(parsed) ||
+                    parsed < min ||
+                    (max !== undefined && parsed > max))
+                    throw new UsageError(`Option ${label(option)} accepts an integer ${max === undefined ? `of at least ${min}` : `from ${min} to ${max}`}; got ${value}`);
+            }
+        }
+    }
+    const spec = grammar.positionals;
+    if (rest.length > spec.max)
+        throw new UsageError(spec.max === 0
+            ? `Unexpected argument ${rest[0]}`
+            : `Expected at most ${spec.max} <${spec.name}>; got ${rest.length}`);
+    if (rest.length < spec.min)
+        throw new UsageError(`Expected <${spec.name}>`);
+    return {
+        positionals: rest,
+        flag: (name) => flags.has(name),
+        value: (name) => values.get(name)?.[0],
+        list: (name) => values.get(name) ?? [],
+        integer: (name, fallback) => {
+            const raw = values.get(name)?.[0];
+            return raw === undefined ? fallback : Number(raw);
+        },
+    };
+}
+//# sourceMappingURL=args.js.map

package/dist/args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.js","sourceRoot":"","sources":["../src/args.ts"],"names":[],"mappings":"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"}

package/dist/briefing.d.ts

@@ -0,0 +1,76 @@
+/**
+ * docs/specs/host-plugin-distribution/README.md §8.2: what the session hook tells the model and the user.
+ * A pure function of facts `ia doctor` already gathered, so every row of §8.2 is a unit test. At most one notice:
+ * version skew, then an interrupted installation or a stale or missing host, then a decline reminder, then an update.
+ * Dates are the user's local calendar date, as the `declined-today` expiry is (§9.1).
+ *
+ * `nextActions` is §7.3's `[{intent, argv, host}]`: `host` is the adapter row's own invocation where §4's table
+ * declares one (Claude's `/ia:init`), otherwise the plain command. The Claude plugin is a Claude concern, so its version
+ * skew is reported only to a host whose row installs a plugin; a host with no workspace set (§4, Cursor) is never told
+ * its registration is missing, because `ia host` would refuse to write one. When doctor could not observe the host set
+ * (an interrupted installation, or installed state it could not read) the briefing says so, for every host, and never
+ * suggests `ia host`, which would refuse until recovery runs.
+ *
+ * One report has one root. Given `--root`, doctor reports that directory literally, so every command the briefing
+ * names carries it the way its verb takes a directory: `ia host <host> --root <root>`, and `ia init <root>` (init takes
+ * its target as a positional and refuses `--root`). A host's own invocation runs in the session's project directory,
+ * so it is used only without `--root`. `ia host <host> --user` belongs to no workspace and refuses `--root`, so it
+ * never carries one. A supplied directory that is not itself a workspace but lies inside one is neither offered
+ * initialization nor described: the briefing names the enclosing workspace and the command that reports it.
+ */
+import type { Decision } from '@inventarch/distribution/decisions';
+import type { Intent } from '@inventarch/distribution/hosts';
+import type { Channel } from './channel.js';
+export interface NextAction {
+    readonly intent: Intent;
+    readonly argv: readonly string[];
+    /** The host's own invocation when its adapter row declares one and no --root was given; otherwise the plain command. */
+    readonly host: string;
+}
+export interface Session {
+    /** Lines for the model (§8.1 step 3's `additionalContext`). */
+    readonly context: readonly string[];
+    /** The one line the user sees, or null in the §8.2 states where the user sees nothing. */
+    readonly notice: string | null;
+    /** 'update' when the notice is an update nudge, which the hook shows at most once per local day (Amendment item 4). */
+    readonly nudge: 'update' | null;
+    /** The argument vector the hook starts detached to refresh the update cache, or null when none is due (Amendment item 4). */
+    readonly refresh: readonly string[] | null;
+}
+export interface BriefInput {
+    readonly host: string;
+    readonly version: string;
+    readonly channel: Channel;
+    /** The CLI version the materialized Claude plugin records, or null when it is absent or unreadable. */
+    readonly plugin: {
+        readonly cli: string;
+    } | null;
+    /** The workspace root, or undefined when there is no workspace. */
+    readonly root: string | undefined;
+    /** The `--root` doctor was given, or undefined when it discovered the root from the working directory. */
+    readonly supplied: string | undefined;
+    /** The workspace a supplied non-workspace directory lies inside, or null. */
+    readonly enclosing: string | null;
+    readonly frameworkSource: boolean;
+    readonly decision: Decision | null;
+    /** The records row's detail, or null when records were not read. */
+    readonly records: string | null;
+    /** 'unknown' when doctor could not observe the host set; 'absent' only when it observed none for this host. */
+    readonly hostStatus: 'registered' | 'stale' | 'absent' | 'unknown';
+    /** Why the host is stale, or why it was not observed: the failing rows' details, for the model. */
+    readonly hostDetail: string | null;
+    /** The pending row's remedy when an interrupted installation needs recovery, else null. */
+    readonly recovery: string | null;
+    readonly updates: {
+        readonly latest: string | null;
+        readonly behind: number | null;
+    } | null;
+    readonly refresh: readonly string[] | null;
+}
+/** A timestamp as the user's local calendar date, YYYY-MM-DD. */
+export declare const localDate: (at: string) => string;
+export declare function brief(input: BriefInput): {
+    readonly session: Session;
+    readonly nextActions: readonly NextAction[];
+};
+//# sourceMappingURL=briefing.d.ts.map

package/dist/briefing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"briefing.d.ts","sourceRoot":"","sources":["../src/briefing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oCAAoC,CAAC;AACnE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gCAAgC,CAAC;AAE7D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAI5C,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,wHAAwH;IACxH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AACD,MAAM,WAAW,OAAO;IACtB,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,0FAA0F;IAC1F,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,uHAAuH;IACvH,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAAC;IAChC,6HAA6H;IAC7H,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;CAC5C;AACD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,uGAAuG;IACvG,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACjD,mEAAmE;IACnE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,0GAA0G;IAC1G,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;IACnC,oEAAoE;IACpE,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,+GAA+G;IAC/G,QAAQ,CAAC,UAAU,EAAE,YAAY,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAC;IACnE,mGAAmG;IACnG,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,2FAA2F;IAC3F,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;IAC5F,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;CAC5C;AAQD,iEAAiE;AACjE,eAAO,MAAM,SAAS,GAAI,IAAI,MAAM,KAAG,MAAkD,CAAC;AAE1F,wBAAgB,KAAK,CAAC,KAAK,EAAE,UAAU,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,SAAS,UAAU,EAAE,CAAA;CAAE,CAgGnH"}

package/dist/briefing.js

@@ -0,0 +1,105 @@
+import { hostRow, invocation, workspaceRow } from '@inventarch/distribution/hosts';
+import { describeChannel, updateInstruction } from './channel.js';
+import { quote } from './render.js';
+/** An argument vector as one printable command, each argument quoted the way doctor's rows quote a root. */
+const command = (argv) => argv.map(quote).join(' ');
+/**
+ * The host as every notice and context line names it: `Claude`, `Codex`, `Cursor`. The adapter row's label is the
+ * product name ("Claude Code"); these lines name the host the way §8.2's own wording does.
+ */
+const named = (host) => host.charAt(0).toUpperCase() + host.slice(1);
+/** A timestamp as the user's local calendar date, YYYY-MM-DD. */
+export const localDate = (at) => new Date(at).toLocaleDateString('en-CA');
+export function brief(input) {
+    const context = [`ia ${input.version} (${describeChannel(input.channel)}).`];
+    const actions = [];
+    const rooted = input.supplied !== undefined;
+    const action = (intent, argv) => ({
+        intent,
+        argv,
+        host: rooted ? command(argv) : invocation(input.host, intent, argv),
+    });
+    let notice = null, nudge = null;
+    const first = (text) => {
+        if (notice === null)
+            notice = text;
+    };
+    // §8.2 row 2: the plugin the user runs was rendered by another ia; re-rendering it is the whole remedy.
+    if (hostRow(input.host)?.user === 'plugin' && input.plugin !== null && input.plugin.cli !== input.version) {
+        const user = ['ia', 'host', input.host, '--user', '--apply'];
+        first(`IA: the plugin was installed by ia ${input.plugin.cli} but ia is ${input.version}; run ${command(user)}`);
+        context.push(`The ${named(input.host)} plugin was installed by ia ${input.plugin.cli}; this is ia ${input.version}. Run ${command(user)}.`);
+        actions.push(action('host-user', user));
+    }
+    if (input.frameworkSource) {
+        context.push(`This is the InventArch framework source (${input.root}). Use its CLAUDE.md and pnpm gates; consumer workspace advice does not apply here.`);
+    }
+    else if (input.root === undefined && input.enclosing !== null) {
+        // The report is about the supplied directory, not the workspace above it; name that workspace and stop.
+        context.push(`${input.supplied} is inside InventArch workspace ${input.enclosing}; run ${command(['ia', 'doctor', '--root', input.enclosing])} for its state.`);
+    }
+    else if (input.root === undefined) {
+        const decision = input.decision;
+        if (decision?.decision === 'declined-forever') {
+            const on = localDate(decision.at);
+            first(`IA not installed in ${decision.path}; declined by user ${on}`);
+            context.push(`The user declined InventArch here permanently on ${on}. Do not offer initialization. "ia init" still works if the user asks for it explicitly.`);
+        }
+        else if (decision?.decision === 'declined-today') {
+            context.push('The user declined initialization here today. Do not offer it again.');
+        }
+        else {
+            // §8.3: an instruction to the model, not a mechanical guarantee.
+            const init = action('init', ['ia', 'init', input.supplied ?? '.']);
+            context.push(`${rooted ? `${input.supplied} is` : 'This directory is'} not an InventArch workspace. Do not search the filesystem for other .ia trees or IA tooling. Offer initialization only if the user's request involves InventArch, .ia records or their governance; then use ${init.host === command(init.argv) ? `"${init.host}"` : init.host}.`);
+            actions.push(init);
+        }
+    }
+    else {
+        context.push(`InventArch workspace ${input.root}: ${input.records ?? 'records not read'}.`);
+        const label = named(input.host);
+        const apply = [
+            'ia',
+            'host',
+            input.host,
+            ...(input.supplied === undefined ? [] : ['--root', input.supplied]),
+            '--apply',
+        ];
+        if (input.hostStatus === 'unknown') {
+            // Every ia host plan refuses until recovery runs, so recovery is the only command worth naming, for any host.
+            if (input.recovery !== null)
+                first(`IA: an interrupted installation needs recovery; run ${input.recovery}`);
+            context.push(`Host ${label}: not checked${input.hostDetail === null ? '' : ` (${input.hostDetail})`}.${input.recovery === null ? '' : ` An interrupted installation needs recovery first: ${input.recovery}.`} Do not run ia host until ia doctor reports the host set.`);
+        }
+        else if (workspaceRow(input.host) === undefined)
+            context.push(`Host ${label} has no workspace registration in this ia.`);
+        else if (input.hostStatus === 'registered')
+            context.push(`Host ${label}: registered.`);
+        else {
+            if (input.hostStatus === 'stale') {
+                first(`IA: the ${label} host registration for this workspace is stale; run ${command(apply)}`);
+                context.push(`Host ${label}: stale${input.hostDetail === null ? '' : ` — ${input.hostDetail}`}. Run ${command(apply)}.`);
+            }
+            else {
+                first(`IA: this workspace has no ${label} host registration; run ${command(apply)}`);
+                context.push(`Host ${label}: not registered. Run ${command(apply)}.`);
+            }
+            actions.push(action('host', apply));
+        }
+    }
+    // §8.2 last row and §11: only from the cache doctor already read; the hook, not doctor, limits it to once a day.
+    const updates = input.updates;
+    const newer = updates !== null && updates.latest !== null && updates.latest !== input.version;
+    if (updates !== null && (newer || (updates.behind ?? 0) > 0)) {
+        const what = newer
+            ? `ia ${updates.latest} is available (you have ${input.version})`
+            : `your checkout is ${updates.behind} commits behind its upstream`;
+        context.push(`Update: ${what}. ${updateInstruction(input.channel)}.`);
+        if (notice === null) {
+            notice = `IA: ${what}. ${updateInstruction(input.channel)}`;
+            nudge = 'update';
+        }
+    }
+    return { session: { context, notice, nudge, refresh: input.refresh }, nextActions: actions };
+}
+//# sourceMappingURL=briefing.js.map

package/dist/briefing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"briefing.js","sourceRoot":"","sources":["../src/briefing.ts"],"names":[],"mappings":"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"}

package/dist/channel.d.ts

@@ -0,0 +1,22 @@
+export type Channel = {
+    readonly kind: 'checkout';
+    readonly root: string;
+    readonly commit: string | null;
+    readonly dirty: boolean | null;
+    readonly origin: string | null;
+} | {
+    readonly kind: 'npm';
+    readonly name: string;
+    readonly version: string;
+} | {
+    readonly kind: 'unknown';
+    readonly entry: string;
+};
+export type Git = (cwd: string, args: readonly string[]) => string | null;
+export declare const runGit: Git;
+/** §5's table, top to bottom: under node_modules is npm; inside this repository's own work tree is a checkout. */
+export declare function detectChannel(packageRoot: string, git?: Git): Channel;
+/** §5's update instruction for the channel, as the hook and doctor print it. */
+export declare function updateInstruction(channel: Channel): string;
+export declare function describeChannel(channel: Channel): string;
+//# sourceMappingURL=channel.d.ts.map

package/dist/channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AASA,MAAM,MAAM,OAAO,GACf;IACE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACzE;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AACzD,MAAM,MAAM,GAAG,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK,MAAM,GAAG,IAAI,CAAC;AAC1E,eAAO,MAAM,MAAM,EAAE,GAUpB,CAAC;AASF,kHAAkH;AAClH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,GAAE,GAAY,GAAG,OAAO,CA8B7E;AACD,gFAAgF;AAChF,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAK1D;AACD,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAKxD"}

package/dist/channel.js

@@ -0,0 +1,74 @@
+/**
+ * Host plugin distribution spec §5: how this installation of `ia` is running, read from where its package sits.
+ * Only the filesystem and local git are consulted; nothing here touches the network.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { dirname, resolve, sep } from 'node:path';
+import { sameFile } from '@inventarch/db';
+export const runGit = (cwd, args) => {
+    // --no-optional-locks: doctor calls this on every session start, and it must never contend with a concurrent
+    // git process for the index lock. 700ms each: three sequential calls (rev-parse, status, config) must leave
+    // headroom inside the hook's 5s doctor budget for workspace validation.
+    const result = spawnSync('git', ['--no-optional-locks', '-C', cwd, ...args], {
+        encoding: 'utf8',
+        timeout: 700,
+        windowsHide: true,
+    });
+    return result.status === 0 ? result.stdout.trim() : null;
+};
+const real = (path) => {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return resolve(path);
+    }
+};
+/** §5's table, top to bottom: under node_modules is npm; inside this repository's own work tree is a checkout. */
+export function detectChannel(packageRoot, git = runGit) {
+    const root = real(packageRoot);
+    if (root.split(sep).includes('node_modules')) {
+        try {
+            const manifest = JSON.parse(readFileSync(resolve(root, 'package.json'), 'utf8'));
+            return { kind: 'npm', name: manifest.name ?? 'unknown', version: manifest.version ?? '0.0.0' };
+        }
+        catch {
+            return { kind: 'unknown', entry: resolve(root, 'dist/main.js') };
+        }
+    }
+    for (let current = root;; current = dirname(current)) {
+        if (existsSync(resolve(current, '.git'))) {
+            if (existsSync(resolve(current, 'pnpm-workspace.yaml')) && sameFile(resolve(current, 'apps/cli'), root)) {
+                const status = git(current, ['status', '--porcelain', '--untracked-files=no']);
+                return {
+                    kind: 'checkout',
+                    root: current,
+                    commit: git(current, ['rev-parse', 'HEAD']),
+                    dirty: status === null ? null : status !== '',
+                    origin: git(current, ['config', '--get', 'remote.origin.url']),
+                };
+            }
+            break;
+        }
+        if (dirname(current) === current)
+            break;
+    }
+    return { kind: 'unknown', entry: resolve(root, 'dist/main.js') };
+}
+/** §5's update instruction for the channel, as the hook and doctor print it. */
+export function updateInstruction(channel) {
+    if (channel.kind === 'checkout')
+        return `In ${channel.root}: git pull, pnpm build, then ia host claude --user --apply`;
+    if (channel.kind === 'npm')
+        return `npm i -g ${channel.name}@latest, then ia host claude --user --apply`;
+    return 'Reinstall ia from its source, then run ia host claude --user --apply';
+}
+export function describeChannel(channel) {
+    if (channel.kind === 'checkout')
+        return `checkout ${channel.root}${channel.commit ? ` at ${channel.commit.slice(0, 12)}` : ''}${channel.dirty === true ? ', uncommitted changes' : channel.dirty === null ? ', dirty state unknown' : ''}${channel.origin ? `, origin ${channel.origin}` : ''}`;
+    if (channel.kind === 'npm')
+        return `npm package ${channel.name} ${channel.version}`;
+    return `unknown install; running from ${channel.entry}`;
+}
+//# sourceMappingURL=channel.js.map

package/dist/channel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.js","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"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"}

package/dist/claude-cli.d.ts

@@ -0,0 +1,35 @@
+import type { SpawnSyncReturns } from 'node:child_process';
+type Env = Readonly<Record<string, string | undefined>>;
+export declare const PLUGIN_ID = "ia@inventarch";
+/** null: not known, because claude is unavailable or its list did not parse. */
+export interface ClaudeState {
+    readonly marketplaceKnown: boolean | null;
+    readonly installed: boolean | null;
+}
+export interface ClaudeRunner {
+    readonly available: boolean;
+    /** `stdout` alone is what a `--json` list is parsed from; `output` is both streams, for a refusal to quote. */
+    readonly run: (args: readonly string[]) => {
+        readonly status: number | null;
+        readonly stdout: string;
+        readonly output: string;
+    };
+}
+/**
+ * §2.3's observed shapes: `plugin marketplace list --json` is an array of `{name, …}` and `plugin list --json` an
+ * array of `{id, scope, …}`. Only a user-scope install is ours to remove; a row without a scope is taken as one.
+ */
+export declare function observeClaude(runner: ClaudeRunner): ClaudeState;
+/** §2.3: `marketplace add` and `install` are both idempotent, so registration is always the same two commands. */
+export declare const registrationCommands: (marketplace: string) => string[][];
+/** §2.3: `uninstall` and `remove` exit 1 when there is nothing to remove, so only what is listed (or unknown) is removed. */
+export declare function removalCommands(state: ClaudeState): string[][];
+export type Spawn = (command: string, args: readonly string[], options: Readonly<Record<string, unknown>>) => SpawnSyncReturns<string>;
+/** Injected only by tests, which exercise the Windows resolution without running a real `claude`. */
+export interface RunnerDependencies {
+    readonly platform: NodeJS.Platform;
+    readonly spawn: Spawn;
+}
+export declare function claudeRunner(env: Env, dependencies?: RunnerDependencies): ClaudeRunner;
+export {};
+//# sourceMappingURL=claude-cli.d.ts.map

package/dist/claude-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-cli.d.ts","sourceRoot":"","sources":["../src/claude-cli.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAK3D,KAAK,GAAG,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;AACxD,eAAO,MAAM,SAAS,kBAA2C,CAAC;AAClE,gFAAgF;AAChF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,gBAAgB,EAAE,OAAO,GAAG,IAAI,CAAC;IAC1C,QAAQ,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI,CAAC;CACpC;AACD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,+GAA+G;IAC/G,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK;QACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;KACzB,CAAC;CACH;AAeD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,WAAW,CAc/D;AACD,kHAAkH;AAClH,eAAO,MAAM,oBAAoB,GAAI,aAAa,MAAM,KAAG,MAAM,EAAE,EAGlE,CAAC;AACF,6HAA6H;AAC7H,wBAAgB,eAAe,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,EAAE,EAAE,CAK9D;AAOD,MAAM,MAAM,KAAK,GAAG,CAClB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,KACvC,gBAAgB,CAAC,MAAM,CAAC,CAAC;AAC9B,qGAAqG;AACrG,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;CACvB;AAoBD,wBAAgB,YAAY,CAAC,GAAG,EAAE,GAAG,EAAE,YAAY,GAAE,kBAA6B,GAAG,YAAY,CAgChG"}