@canonical/pragma-cli 0.33.0 → 0.35.0

package/dist/src/capabilities/upgrade/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/capabilities/upgrade/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/src/capabilities/upgrade/runUpgrade.js

@@ -0,0 +1,99 @@
+/**
+ * Build the `upgrade` Task (lazily imported, off the fast path).
+ *
+ * Async-setup then compose: read the channel, detect the install source, and
+ * check the registry (a preview-safe READ — no side effect), then return a Task
+ * shaped by the outcome. The `exec` effect is the SOLE mutation, so the effect
+ * seam does the rest for free:
+ *
+ * - `--dry-run` (dispatcher `dryRun`) MOCKS the exec and describes the plan —
+ *   both the `Log` version-delta line AND the `Execute: <command>` line show,
+ *   and nothing runs.
+ * - `--yes` / MCP `confirm` runs the exec for real; a nonzero exit is surfaced
+ *   by `assertExecOk` as an actionable UNSUPPORTED (exit 1) — the interpreter
+ *   RESOLVES on a nonzero exit, so the check is the consumer's job.
+ * - offline / already-latest carry NO exec — a real run just returns the status.
+ *
+ * The whole registry read is preview-safe, so no `mutation.preview` gating is
+ * needed here (unlike `sources update`, whose heavy resolve must be gated).
+ * `run` returns `Promise<Task<R>>`, presented through the `Task<R>` arm by the
+ * honest cast at the verb (the `update.verb.ts` precedent).
+ */
+import { $, exec, gen, info, warn } from "@canonical/task";
+import { assertExecOk, checkRegistryVersion, detectInstallSource, guardMissingBinary, PRAGMA_PACKAGE, pmUpdateCommand, } from "../shared/index.js";
+/**
+ * Resolve the upgrade state and compose the corresponding Task.
+ *
+ * @param rt - The per-invocation runtime.
+ * @returns A Task yielding the upgrade outcome (its exec runs only on a real,
+ *   update-needed execution).
+ * @note Impure — reads the config + the registry (the exec is the only mutation,
+ *   and it runs only under a real, update-needed execution).
+ */
+export async function runUpgrade(rt) {
+    const { channel } = (await rt.loadConfig()).config;
+    const install = detectInstallSource();
+    const command = pmUpdateCommand(install.pm, PRAGMA_PACKAGE);
+    const pm = install.label;
+    const current = rt.version;
+    const registry = await checkRegistryVersion(PRAGMA_PACKAGE, channel);
+    if (registry === undefined) {
+        const data = {
+            pm,
+            current,
+            latest: undefined,
+            command,
+            offline: true,
+            alreadyLatest: false,
+            executed: false,
+        };
+        return gen(function* () {
+            yield* $(warn("Cannot reach the registry — skipped the update check."));
+            return data;
+        });
+    }
+    if (registry.latest === current) {
+        const data = {
+            pm,
+            current,
+            latest: registry.latest,
+            command,
+            offline: false,
+            alreadyLatest: true,
+            executed: false,
+        };
+        return gen(function* () {
+            yield* $(info(`Already at the latest version (${current}).`));
+            return data;
+        });
+    }
+    const data = {
+        pm,
+        current,
+        latest: registry.latest,
+        command,
+        offline: false,
+        alreadyLatest: false,
+        executed: true,
+    };
+    const parts = command.split(" ");
+    const bin = parts[0] ?? "npm";
+    const args = parts.slice(1);
+    // Guard the spawn: an absent package manager (`bin` not on PATH) REJECTS the
+    // exec with ENOENT, which would collapse to INTERNAL_ERROR ("report
+    // this issue"). Surface it as a named "`<pm>` not found on PATH" instead.
+    return guardMissingBinary(bin, {
+        message: `Install ${pm} (or your package manager) and ensure it is on your PATH, then try again.`,
+    }, gen(function* () {
+        // The version-delta rides a Log effect, so `--dry-run` describes it too.
+        yield* $(info(`${current} → ${registry.latest}`));
+        // The one mutation — mocked under dry-run, run for real under --yes/confirm.
+        // The interpreter RESOLVES on a nonzero exit (only a spawn error rejects),
+        // so inspect the result: a failed install (e.g. EACCES on a global
+        // `npm i -g`) must fail loudly, not report a silent success.
+        const result = yield* $(exec(bin, args, rt.cwd));
+        assertExecOk(command, result);
+        return data;
+    }));
+}
+//# sourceMappingURL=runUpgrade.js.map

package/dist/src/capabilities/upgrade/runUpgrade.js.map

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

package/dist/src/capabilities/upgrade/types.js

@@ -0,0 +1,5 @@
+/**
+ * Data shape for `pragma upgrade`.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/capabilities/upgrade/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/capabilities/upgrade/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/src/capabilities/upgrade/upgrade.render.js

@@ -0,0 +1,44 @@
+/**
+ * Formatters for `pragma upgrade` — plain (chalk), llm, json.
+ *
+ * Renders the REAL-run outcome (the `--dry-run` plan is rendered by the
+ * dispatcher's plan renderer, not here), so there is no "would run" branch: a
+ * needed run always carries `executed: true`.
+ */
+import chalk from "chalk";
+import { PRAGMA_PACKAGE } from "../shared/index.js";
+export const upgradeFormatters = {
+    plain(data) {
+        const lines = [`Installed via: ${data.pm}`];
+        if (data.offline) {
+            lines.push("Cannot reach the registry — try again later.");
+            return lines.join("\n");
+        }
+        if (data.alreadyLatest) {
+            lines.push(`Already at the latest version (${data.current}).`);
+            return lines.join("\n");
+        }
+        lines.push("", `${PRAGMA_PACKAGE}  ${data.current} → ${chalk.green(String(data.latest))}`, "");
+        if (data.executed) {
+            lines.push(`Ran: ${chalk.cyan(data.command)}`, "", `Updated to ${data.latest}.`);
+        }
+        else {
+            lines.push(`Run: ${chalk.cyan(data.command)}`);
+        }
+        return lines.join("\n");
+    },
+    llm(data) {
+        if (data.offline)
+            return "Upgrade check failed: cannot reach the registry.";
+        if (data.alreadyLatest) {
+            return `Already at the latest version (${data.current}).`;
+        }
+        if (data.executed)
+            return `Upgraded: ${data.current} → ${data.latest}`;
+        return `Update available: ${data.current} → ${data.latest} (\`${data.command}\`)`;
+    },
+    json(data) {
+        return JSON.stringify(data);
+    },
+};
+//# sourceMappingURL=upgrade.render.js.map

package/dist/src/capabilities/upgrade/upgrade.render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade.render.js","sourceRoot":"","sources":["../../../../src/capabilities/upgrade/upgrade.render.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAGpD,MAAM,CAAC,MAAM,iBAAiB,GAA4B;IACxD,KAAK,CAAC,IAAI;QACR,MAAM,KAAK,GAAG,CAAC,kBAAkB,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;QAC5C,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,KAAK,CAAC,IAAI,CAAC,8CAA8C,CAAC,CAAC;YAC3D,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC;QACD,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YACvB,KAAK,CAAC,IAAI,CAAC,kCAAkC,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC;YAC/D,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC;QACD,KAAK,CAAC,IAAI,CACR,EAAE,EACF,GAAG,cAAc,KAAK,IAAI,CAAC,OAAO,MAAM,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,EAAE,EAC1E,EAAE,CACH,CAAC;QACF,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,KAAK,CAAC,IAAI,CACR,QAAQ,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,EAClC,EAAE,EACF,cAAc,IAAI,CAAC,MAAM,GAAG,CAC7B,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,KAAK,CAAC,IAAI,CAAC,QAAQ,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QACjD,CAAC;QACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED,GAAG,CAAC,IAAI;QACN,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO,kDAAkD,CAAC;QAC5E,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YACvB,OAAO,kCAAkC,IAAI,CAAC,OAAO,IAAI,CAAC;QAC5D,CAAC;QACD,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO,aAAa,IAAI,CAAC,OAAO,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC;QACvE,OAAO,qBAAqB,IAAI,CAAC,OAAO,MAAM,IAAI,CAAC,MAAM,OAAO,IAAI,CAAC,OAAO,KAAK,CAAC;IACpF,CAAC;IAED,IAAI,CAAC,IAAI;QACP,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;CACF,CAAC"}

package/dist/src/capabilities/upgrade/upgrade.verb.js

@@ -0,0 +1,52 @@
+/**
+ * The `upgrade` verb spec (noun `upgrade`, self-verb).
+ *
+ * A storeless, network-touching mutation: check the registry, then run the
+ * package-manager update. `destructive: false` is load-bearing (D4) — upgrading
+ * replaces the binary, it destroys no user data — so `annotationsFor` emits
+ * `destructiveHint: false` rather than letting MCP clients default an unset hint
+ * on a non-read-only tool to `true`.
+ *
+ * `run` returns `Promise<Task<UpgradeData>>` (async registry read before the
+ * effects are known) presented through the `Task<R>` arm by the honest cast —
+ * the `update.verb.ts` precedent; a literal `Promise<Task>` union arm would
+ * poison async read-verb inference.
+ */
+import { BIN_NAME } from "../../constants.js";
+import { asVerb } from "../../kernel/spec/asVerb.js";
+import { upgradeFormatters } from "./upgrade.render.js";
+const upgradeVerb = {
+    path: ["upgrade"],
+    summary: `Upgrade the ${BIN_NAME} CLI to the latest version.`,
+    doc: "Checks the registry for the active channel's latest release and runs your package manager's global-update command. Preview the update before applying it.",
+    params: [],
+    output: { formatters: upgradeFormatters },
+    examples: [
+        { cmd: `${BIN_NAME} upgrade` },
+        {
+            cmd: `${BIN_NAME} upgrade --dry-run`,
+            note: "show the delta and the command",
+        },
+    ],
+    capability: {
+        needsStore: false,
+        mutates: true,
+        destructive: false,
+        needsNetwork: true,
+        mcp: {
+            expose: true,
+            annotations: {
+                readOnlyHint: false,
+                destructiveHint: false,
+                openWorldHint: false,
+            },
+        },
+    },
+    run: (_params, runtime) => import("./runUpgrade.js").then((m) => m.runUpgrade(runtime)),
+};
+/** The `upgrade` capability module. */
+export const upgradeModule = {
+    name: "upgrade",
+    verbs: [asVerb(upgradeVerb)],
+};
+//# sourceMappingURL=upgrade.verb.js.map

package/dist/src/capabilities/upgrade/upgrade.verb.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade.verb.js","sourceRoot":"","sources":["../../../../src/capabilities/upgrade/upgrade.verb.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAE,MAAM,6BAA6B,CAAC;AAGrD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAExD,MAAM,WAAW,GAAmD;IAClE,IAAI,EAAE,CAAC,SAAS,CAAC;IACjB,OAAO,EAAE,eAAe,QAAQ,6BAA6B;IAC7D,GAAG,EAAE,2JAA2J;IAChK,MAAM,EAAE,EAAE;IACV,MAAM,EAAE,EAAE,UAAU,EAAE,iBAAiB,EAAE;IACzC,QAAQ,EAAE;QACR,EAAE,GAAG,EAAE,GAAG,QAAQ,UAAU,EAAE;QAC9B;YACE,GAAG,EAAE,GAAG,QAAQ,oBAAoB;YACpC,IAAI,EAAE,gCAAgC;SACvC;KACF;IACD,UAAU,EAAE;QACV,UAAU,EAAE,KAAK;QACjB,OAAO,EAAE,IAAI;QACb,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE,IAAI;QAClB,GAAG,EAAE;YACH,MAAM,EAAE,IAAI;YACZ,WAAW,EAAE;gBACX,YAAY,EAAE,KAAK;gBACnB,eAAe,EAAE,KAAK;gBACtB,aAAa,EAAE,KAAK;aACrB;SACF;KACF;IACD,GAAG,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,CACxB,MAAM,CAAC,iBAAiB,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CACnC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,CACU;CACpC,CAAC;AAEF,uCAAuC;AACvC,MAAM,CAAC,MAAM,aAAa,GAAqB;IAC7C,IAAI,EAAE,SAAS;IACf,KAAK,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;CAC7B,CAAC"}

package/dist/src/capabilities/version/index.js

@@ -0,0 +1,10 @@
+/**
+ * The `version` capability barrel — the command form of `--version`.
+ */
+import { versionVerbSpec } from "./version.verb.js";
+/** The `version` capability module. */
+export const versionModule = {
+    name: "version",
+    verbs: [versionVerbSpec],
+};
+//# sourceMappingURL=index.js.map

package/dist/src/capabilities/version/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/capabilities/version/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD,uCAAuC;AACvC,MAAM,CAAC,MAAM,aAAa,GAAqB;IAC7C,IAAI,EAAE,SAAS;IACf,KAAK,EAAE,CAAC,eAAe,CAAC;CACzB,CAAC"}

package/dist/src/capabilities/version/version.verb.js

@@ -0,0 +1,36 @@
+/**
+ * `pragma version` — the command form of `--version`.
+ *
+ * Users type it reflexively, so it exists and prints exactly the bytes the
+ * flag prints: the bare semver on stdout, storeless, no store or network
+ * touched. Withheld from MCP — the version already rides `info` and the
+ * server handshake's `serverInfo`.
+ */
+import { BIN_NAME, VERSION } from "../../constants.js";
+import { asVerb } from "../../kernel/spec/asVerb.js";
+const versionVerb = {
+    path: ["version"],
+    summary: "Print the CLI version.",
+    doc: "Prints the version `--version` prints — one value, two spellings of the same read.",
+    params: [],
+    output: {
+        formatters: {
+            plain: (version) => version,
+            llm: (version) => version,
+            json: (version) => JSON.stringify({ version }),
+        },
+    },
+    examples: [{ cmd: `${BIN_NAME} version` }],
+    capability: {
+        needsStore: false,
+        mutates: false,
+        mcp: {
+            expose: false,
+            reason: "the version rides `info` and the MCP handshake's serverInfo",
+        },
+    },
+    run: async () => VERSION,
+};
+/** The `version` verb. */
+export const versionVerbSpec = asVerb(versionVerb);
+//# sourceMappingURL=version.verb.js.map

package/dist/src/capabilities/version/version.verb.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.verb.js","sourceRoot":"","sources":["../../../../src/capabilities/version/version.verb.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,MAAM,EAAE,MAAM,6BAA6B,CAAC;AAGrD,MAAM,WAAW,GAA8C;IAC7D,IAAI,EAAE,CAAC,SAAS,CAAC;IACjB,OAAO,EAAE,wBAAwB;IACjC,GAAG,EAAE,oFAAoF;IACzF,MAAM,EAAE,EAAE;IACV,MAAM,EAAE;QACN,UAAU,EAAE;YACV,KAAK,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO;YAC3B,GAAG,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO;YACzB,IAAI,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,CAAC;SAC/C;KACF;IACD,QAAQ,EAAE,CAAC,EAAE,GAAG,EAAE,GAAG,QAAQ,UAAU,EAAE,CAAC;IAC1C,UAAU,EAAE;QACV,UAAU,EAAE,KAAK;QACjB,OAAO,EAAE,KAAK;QACd,GAAG,EAAE;YACH,MAAM,EAAE,KAAK;YACb,MAAM,EAAE,6DAA6D;SACtE;KACF;IACD,GAAG,EAAE,KAAK,IAAI,EAAE,CAAC,OAAO;CACzB,CAAC;AAEF,0BAA0B;AAC1B,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC"}

package/dist/src/constants.js

@@ -0,0 +1,82 @@
+/**
+ * Package-level constants — the distribution's identity, projected.
+ *
+ * The bin name, MCP server name, description and issues URL are NOT authored
+ * here: they are read from the distribution config (`pragma.conf.ts`), so a fork
+ * changes values, not code. The import is static because the surfaces that need
+ * identity — `--help`, `__complete`, first-run onboarding, the MCP handshake —
+ * all run before or without the config layer. That is safe precisely because
+ * `pragma.conf.ts` is inert data: a plain object literal whose only import is a
+ * type. It reaches no zod schema, no fs, no evaluator. `capabilities/lazy.test.ts`
+ * pins that boundary, and `src/identity.test.ts` proves the projection.
+ *
+ * Also holds the stable cross-cutting enums: output formats here, and the
+ * detail levels re-exported from `kernel/config/types.ts`, where the config
+ * validator closes the `detail` field over them.
+ */
+import pkg from "../package.json" with { type: "json" };
+import identity from "../pragma.conf.js";
+import { DETAIL_LEVELS } from "./kernel/config/types.js";
+/** CLI binary name — the distribution's `name`. */
+const BIN_NAME = identity.name;
+/**
+ * MCP server identity — the same name as the CLI bin, so agents already pointed
+ * at the server resolve it unchanged. Also the `serverInfo.name` the server
+ * introduces itself with on the wire (paired with {@link VERSION} by
+ * `buildServer`), so a peer reads the distribution's declared name, never a
+ * hardcoded one.
+ */
+const MCP_SERVER_NAME = identity.name;
+/** One-line program description for help and server metadata. */
+const PROGRAM_DESCRIPTION = identity.help;
+/** Where the distribution asks users to file issues and feedback. */
+const ISSUES_URL = identity.issuesUrl;
+/** Semver version string read from package.json. */
+const VERSION = pkg.version;
+/**
+ * The project config filename the walker looks for and every surface that
+ * quotes it — diagnostics, the onboarding note, the generated reference, the
+ * surface covenant — names. It lives HERE rather than beside the walker so the
+ * quoting surfaces do not have to import `kernel/config/**`: the storeless
+ * `--help`/`__complete` graph is asserted to reach no config module, and
+ * `completion/safety.test.ts` fails the moment one arrives.
+ */
+const PROJECT_CONFIG_FILENAME = `${identity.name}.config.ts`;
+/**
+ * The distribution's name plus a space: the prefix a `recovery.cli` hint carries
+ * so it quotes a command the installed binary answers to (D5). Kernel hints are
+ * authored through `cliRecovery`, which prepends it; `packs/schema.ts` REJECTS
+ * it in a user-authored pack's `emptyRecovery.cli`, because the CONSUMING
+ * distribution's renderer supplies its own. Use {@link BIN_NAME} for prose —
+ * this constant's trailing space belongs to the recovery invariant, not to
+ * sentences.
+ */
+const RECOVERY_CLI_PREFIX = `${identity.name} `;
+/** The output formats the renderer selects between (`llm` = condensed Markdown). */
+const OUTPUT_FORMATS = ["plain", "llm", "json"];
+/** Default detail level when neither flag, config, nor spec pins one. */
+const DEFAULT_DETAIL_LEVEL = "standard";
+/**
+ * The wordmark `--help` opens with, as raw ASCII-art lines.
+ *
+ * PROJECTED from the distribution config, exactly like {@link BIN_NAME} and
+ * {@link PROGRAM_DESCRIPTION} — a wordmark spells a name, so it is identity, and
+ * `kernel/copy.test.ts` forbids any kernel string from naming the distribution.
+ * Authoring the art here would have branded a fork's front door with someone
+ * else's logo; declaring it as data means a fork ships its own or none.
+ *
+ * Lines rather than one string because the art contains a backtick and
+ * backslashes: a template literal would need every one of them escaped, which is
+ * how a character gets lost the next time someone edits it.
+ */
+// Read through the DECLARED type, not the literal's inferred one. The
+// distribution config is `satisfies RawConfig`, which narrows to exactly the
+// keys that file writes — so `identity.logo` does not typecheck in a fork that
+// omits the field, which is precisely the fork this feature promises a bare
+// header. The assignment (not a cast) is what `satisfies` already guarantees,
+// and it makes every OPTIONAL field readable here. The other constants keep
+// reading `identity` directly, so their literal types are untouched.
+const declared = identity;
+const PROGRAM_LOGO = declared.logo ?? [];
+export { BIN_NAME, DEFAULT_DETAIL_LEVEL, DETAIL_LEVELS, ISSUES_URL, MCP_SERVER_NAME, OUTPUT_FORMATS, PROGRAM_DESCRIPTION, PROGRAM_LOGO, PROJECT_CONFIG_FILENAME, RECOVERY_CLI_PREFIX, VERSION, };
+//# sourceMappingURL=constants.js.map

package/dist/src/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,GAAG,MAAM,iBAAiB,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AACxD,OAAO,QAAQ,MAAM,mBAAmB,CAAC;AAEzC,OAAO,EAAE,aAAa,EAAoB,MAAM,0BAA0B,CAAC;AAE3E,mDAAmD;AACnD,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC;AAE/B;;;;;;GAMG;AACH,MAAM,eAAe,GAAG,QAAQ,CAAC,IAAI,CAAC;AAEtC,iEAAiE;AACjE,MAAM,mBAAmB,GAAG,QAAQ,CAAC,IAAI,CAAC;AAE1C,qEAAqE;AACrE,MAAM,UAAU,GAAG,QAAQ,CAAC,SAAS,CAAC;AAEtC,oDAAoD;AACpD,MAAM,OAAO,GAAW,GAAG,CAAC,OAAO,CAAC;AAEpC;;;;;;;GAOG;AACH,MAAM,uBAAuB,GAAG,GAAG,QAAQ,CAAC,IAAI,YAAY,CAAC;AAE7D;;;;;;;;GAQG;AACH,MAAM,mBAAmB,GAAG,GAAG,QAAQ,CAAC,IAAI,GAAG,CAAC;AAEhD,oFAAoF;AACpF,MAAM,cAAc,GAAG,CAAC,OAAO,EAAE,KAAK,EAAE,MAAM,CAAU,CAAC;AASzD,yEAAyE;AACzE,MAAM,oBAAoB,GAAgB,UAAU,CAAC;AAErD;;;;;;;;;;;;GAYG;AACH,sEAAsE;AACtE,6EAA6E;AAC7E,+EAA+E;AAC/E,4EAA4E;AAC5E,8EAA8E;AAC9E,4EAA4E;AAC5E,qEAAqE;AACrE,MAAM,QAAQ,GAAc,QAAQ,CAAC;AAErC,MAAM,YAAY,GAAsB,QAAQ,CAAC,IAAI,IAAI,EAAE,CAAC;AAG5D,OAAO,EACL,QAAQ,EACR,oBAAoB,EACpB,aAAa,EACb,UAAU,EACV,eAAe,EACf,cAAc,EACd,mBAAmB,EACnB,YAAY,EACZ,uBAAuB,EACvB,mBAAmB,EACnB,OAAO,GACR,CAAC"}

package/dist/src/index.js

@@ -0,0 +1,12 @@
+/**
+ * Public, types-only API surface for `@canonical/pragma-cli`.
+ *
+ * Per the tool-ts convention this barrel exports types only — no runtime
+ * values cross the package boundary. Consumers (and the surface emitter's
+ * golden) depend on the grammar and cross-cutting shapes, never on internal
+ * command builders, projectors, or infrastructure.
+ *
+ * @module
+ */
+export {};
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/dist/src/kernel/completion/complete.js

@@ -0,0 +1,66 @@
+/**
+ * `runComplete` — the `__complete` resolver entry point. THE PROTOCOL:
+ *
+ * Invocation: `pragma __complete -- <word1> … <current>`
+ * - The bin fast-paths `argv[0] === "__complete"` literally, BEFORE
+ *   global-flag parsing, Commander, config reads, or first-run — the resolver
+ *   is storeless and config-free by construction. The first `--` after
+ *   `__complete` is protocol framing and is stripped by the bin (tolerated
+ *   absent). A later bare `--` belongs to the user's command line and is
+ *   honoured as end-of-options by the state machine.
+ * - Words are the raw argv after the program name, up to and INCLUDING the
+ *   word being completed — the LAST word is the partial (possibly empty).
+ *   Words after the cursor are never sent. A leading word equal to the bin
+ *   name is stripped (some shells include it).
+ * - Output: matching candidates, newline-delimited, on stdout. Zero
+ *   candidates → zero bytes. Nothing else is ever written to stdout.
+ * - Exit code: ALWAYS 0. `runComplete` never throws — any internal error
+ *   degrades to zero candidates so TAB never breaks a shell.
+ * - stderr is silent unless `PRAGMA_COMPLETE_DEBUG=1`, which logs the
+ *   classified context, "nothing" reasons (unknown noun/verb, exhausted
+ *   positionals, reserved completion kinds), dropped unsafe candidates, and
+ *   timing.
+ * - Shell floors: bash ≥ 4 (mapfile), zsh ≥ 5, fish ≥ 3. bash splits words at
+ *   `=` (COMP_WORDBREAKS), so the state machine treats `=` tokens around a
+ *   value-taking flag as transparent.
+ *
+ * The static scripts (see `emitScripts`) answer structure without exec and
+ * invoke `__complete` only for `{kind:"names"}` value contexts; the resolver
+ * is nevertheless a complete standalone answer for EVERY context, so the
+ * whole grammar is testable through this one function.
+ */
+import { emptyNameSource } from "./entitySource.js";
+import { buildCompletionModel } from "./model.js";
+import { parseWords } from "./parse.js";
+import { completionDebug, resolveRequest } from "./resolve.js";
+/** The default environment: no name sources (callers wire `indexCompletionEnv`). */
+const DEFAULT_ENV = { names: emptyNameSource };
+/**
+ * Resolve completions for the given words against the capability modules.
+ *
+ * Builds the model, parses the words, resolves the request — wrapped in a
+ * never-throw guard: on ANY internal error the answer is zero candidates and
+ * (under `PRAGMA_COMPLETE_DEBUG=1`) a stderr note, never an exception.
+ *
+ * @param words - The command words after the program name; the last is the
+ *   partial being completed (possibly empty).
+ * @param modules - The capability modules to derive the model from.
+ * @param env - The completion environment; defaults to the empty entity seam.
+ * @returns The matching candidates, in offer order.
+ */
+export async function runComplete(words, modules, env = DEFAULT_ENV) {
+    const started = performance.now();
+    try {
+        const model = buildCompletionModel(modules);
+        const request = parseWords(words, model);
+        const candidates = await resolveRequest(request, model, env);
+        completionDebug(`context=${request.context.kind} partial=${JSON.stringify(request.partial)} ` +
+            `candidates=${candidates.length} in ${(performance.now() - started).toFixed(1)}ms`);
+        return candidates;
+    }
+    catch (error) {
+        completionDebug(`error: ${error instanceof Error ? error.message : String(error)}`);
+        return [];
+    }
+}
+//# sourceMappingURL=complete.js.map

package/dist/src/kernel/completion/complete.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"complete.js","sourceRoot":"","sources":["../../../../src/kernel/completion/complete.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAG/D,oFAAoF;AACpF,MAAM,WAAW,GAAkB,EAAE,KAAK,EAAE,eAAe,EAAE,CAAC;AAE9D;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,KAAwB,EACxB,OAAoC,EACpC,MAAqB,WAAW;IAEhC,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;IAClC,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,oBAAoB,CAAC,OAAO,CAAC,CAAC;QAC5C,MAAM,OAAO,GAAG,UAAU,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QACzC,MAAM,UAAU,GAAG,MAAM,cAAc,CAAC,OAAO,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;QAC7D,eAAe,CACb,WAAW,OAAO,CAAC,OAAO,CAAC,IAAI,YAAY,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG;YAC3E,cAAc,UAAU,CAAC,MAAM,OAAO,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CACrF,CAAC;QACF,OAAO,UAAU,CAAC;IACpB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,eAAe,CACb,UAAU,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CACnE,CAAC;QACF,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/src/kernel/completion/emitScripts.js

@@ -0,0 +1,92 @@
+/**
+ * Emit the static shell-completion scripts from the grammar.
+ *
+ * Builds the completion model from the capability modules (the same
+ * derivation the `__complete` resolver uses — the tiers cannot disagree) and
+ * renders one script per supported shell. The static tier answers STRUCTURE
+ * with zero exec: nouns, verbs, flag names, enum values, mutation + global
+ * flags, native file completion. Only `{kind:"names"}` value contexts shell
+ * out to `<bin> __complete`.
+ *
+ * PR6 boundary (`setup completions`): this module exports pure CONTENT only
+ * — shell detection, install paths, mkdir/write effects, and hints all
+ * belong to setup. `binName` is parameterized so a fork's rename reaches the
+ * script body (`completionScriptPath` derives the file NAME from the same
+ * constant, and the two must agree or the shell never loads the file);
+ * `minChars` and `disabledFamilies` are read from `completion` config by setup.
+ *
+ * `minChars` (default {@link DEFAULT_MIN_CHARS}) is baked into the scripts to
+ * gate the `__complete` exec for NAME contexts only — structure and enum values
+ * stay inlined and complete on bare TAB with zero exec. `disabledFamilies`
+ * scrubs a noun's name sources to `none` (the config-level opt-out), so its
+ * name arms drop out of every script; the pack-grammar opt-out (`enabled:false`)
+ * lands earlier, in the model.
+ *
+ * @throws Emitting THROWS on any name outside the safety allowlist (the
+ *   model build asserts, and every template re-asserts what it inlines) —
+ *   `setup completions` fails loudly rather than installing a hostile token.
+ */
+import { BIN_NAME } from "../../constants.js";
+import { assertSafeToken, buildCompletionModel } from "./model.js";
+import { bashScript } from "./templates/bash.js";
+import { fishScript } from "./templates/fish.js";
+import { zshScript } from "./templates/zsh.js";
+/** The default `minChars` gate baked into the generated scripts. */
+export const DEFAULT_MIN_CHARS = 2;
+/** Replace a name source with `none` (the family-level opt-out). */
+function scrubSource(source) {
+    return source.kind === "names" ? { kind: "none" } : source;
+}
+/** Scrub every name source of a verb entry to `none`. */
+function scrubVerb(verb) {
+    return {
+        ...verb,
+        flags: verb.flags.map((flag) => ({
+            ...flag,
+            source: scrubSource(flag.source),
+        })),
+        positionals: verb.positionals.map((positional) => ({
+            ...positional,
+            source: scrubSource(positional.source),
+        })),
+    };
+}
+/**
+ * Drop name completion for the disabled noun families (config opt-out): every
+ * name source under a disabled noun becomes `none`, so no template emits its
+ * exec. A pure structural transform on the model — the templates stay unaware.
+ */
+function applyDisabledFamilies(model, disabled) {
+    if (disabled.size === 0)
+        return model;
+    return {
+        ...model,
+        nouns: model.nouns.map((noun) => disabled.has(noun.noun)
+            ? {
+                ...noun,
+                ...(noun.selfVerb ? { selfVerb: scrubVerb(noun.selfVerb) } : {}),
+                verbs: noun.verbs.map(scrubVerb),
+            }
+            : noun),
+    };
+}
+/**
+ * Emit the completion scripts for every supported shell.
+ *
+ * @param modules - The capability modules to derive completions from.
+ * @param options - Bin name, `minChars` gate, and disabled name families.
+ * @returns A map of shell to its completion script.
+ * @throws Error when any inlinable token fails the safety allowlist.
+ */
+export function emitScripts(modules, options = {}) {
+    const binName = options.binName ?? BIN_NAME;
+    assertSafeToken(binName, "bin name");
+    const minChars = options.minChars ?? DEFAULT_MIN_CHARS;
+    const model = applyDisabledFamilies(buildCompletionModel(modules), new Set(options.disabledFamilies ?? []));
+    return {
+        bash: bashScript(model, binName, minChars),
+        zsh: zshScript(model, binName, minChars),
+        fish: fishScript(model, binName, minChars),
+    };
+}
+//# sourceMappingURL=emitScripts.js.map

package/dist/src/kernel/completion/emitScripts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"emitScripts.js","sourceRoot":"","sources":["../../../../src/kernel/completion/emitScripts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AACnE,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAQ/C,oEAAoE;AACpE,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC;AAYnC,oEAAoE;AACpE,SAAS,WAAW,CAAC,MAAwB;IAC3C,OAAO,MAAM,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;AAC7D,CAAC;AAED,yDAAyD;AACzD,SAAS,SAAS,CAAC,IAAe;IAChC,OAAO;QACL,GAAG,IAAI;QACP,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YAC/B,GAAG,IAAI;YACP,MAAM,EAAE,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC;SACjC,CAAC,CAAC;QACH,WAAW,EAAE,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;YACjD,GAAG,UAAU;YACb,MAAM,EAAE,WAAW,CAAC,UAAU,CAAC,MAAM,CAAC;SACvC,CAAC,CAAC;KACJ,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,qBAAqB,CAC5B,KAAsB,EACtB,QAA6B;IAE7B,IAAI,QAAQ,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACtC,OAAO;QACL,GAAG,KAAK;QACR,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAC9B,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC;YACrB,CAAC,CAAC;gBACE,GAAG,IAAI;gBACP,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAChE,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC;aACjC;YACH,CAAC,CAAC,IAAI,CACT;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CACzB,OAAoC,EACpC,UAA8B,EAAE;IAEhC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,QAAQ,CAAC;IAC5C,eAAe,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IACrC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,iBAAiB,CAAC;IACvD,MAAM,KAAK,GAAG,qBAAqB,CACjC,oBAAoB,CAAC,OAAO,CAAC,EAC7B,IAAI,GAAG,CAAC,OAAO,CAAC,gBAAgB,IAAI,EAAE,CAAC,CACxC,CAAC;IACF,OAAO;QACL,IAAI,EAAE,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC;QAC1C,GAAG,EAAE,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC;QACxC,IAAI,EAAE,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC;KAC3C,CAAC;AACJ,CAAC"}