@canonical/pragma-cli 0.34.0 → 0.35.0

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

@@ -0,0 +1,253 @@
+/**
+ * The argv state machine: classify the word being completed.
+ *
+ * `parseWords(words, model)` scans the words BEFORE the cursor to establish
+ * position — noun, verb (or self-verb), positionals consumed, pending value
+ * flag, end-of-options — then classifies the LAST word (the partial, possibly
+ * empty) into a `CompletionContext`. Pure and storeless: only the model and
+ * the words.
+ *
+ * Scan rules (prior words, in order):
+ * - A pending value flag consumes the next word as its value. A bare `=`
+ *   while pending is transparent — bash splits `--flag=v` into
+ *   `--flag`,`=`,`v` (COMP_WORDBREAKS), so `=` tokens around a value-taking
+ *   flag are wordbreak noise, not values.
+ * - The first bare `--` is the user's end-of-options: everything after is a
+ *   positional, never a flag. (The `__complete -- <words…>` FRAMING `--` was
+ *   already stripped by the bin.)
+ * - A `-…` word (before `--`) is looked up across verb flags → mutation
+ *   flags (mutating verbs) → global flags: known value-taking flags without
+ *   an inline `=` set the pending flag; known flags are marked used;
+ *   unknown flags are skipped silently.
+ * - The first non-flag word is the noun; the second resolves a sub-verb, or
+ *   falls back to the noun's self-verb as its first positional; later ones
+ *   count positionals. Unknown nouns/verbs make non-flag contexts terminal
+ *   (`nothing`), but flag contexts still complete (globals always apply).
+ *
+ * Classification of the current word (first match wins):
+ * 1. pending value flag → flag-value for that flag
+ * 2. `--name=partial` with a known value-taking flag → flag-value
+ * 3. `-…` (before `--`) → flag-name (scoped, used flags de-offered,
+ *    `--version` at root only, mutation flags iff the verb mutates)
+ * 4. no noun yet → noun
+ * 5. unknown noun/verb → nothing
+ * 6. noun with sub-verbs, verb undecided → verb
+ * 7. verb resolved → positional at the running index (a trailing variadic
+ *    absorbs all further indices; past the end → nothing)
+ */
+import { BIN_NAME } from "../../constants.js";
+import { findNoun } from "./model.js";
+/** The resolved verb entry, when one is decided and known. */
+function knownVerb(state) {
+    return typeof state.verb === "object" ? state.verb : undefined;
+}
+/** Every flag entry in scope at the current position (offer order). */
+function flagScope(model, state) {
+    const verb = knownVerb(state);
+    const atRoot = state.noun === undefined;
+    return [
+        ...(verb?.flags ?? []),
+        ...(verb?.mutates ? model.mutationFlags : []),
+        ...model.globalFlags.filter((flag) => atRoot || flag.rootOnly !== true),
+    ];
+}
+/** Look up a flag by its full `--name` token in the current scope. */
+function lookupFlag(model, state, name) {
+    return flagScope(model, state).find((entry) => entry.flag === name);
+}
+/** Consume a prior `-…` word: mark used, maybe set the pending value flag. */
+function scanFlagWord(word, model, state) {
+    const eq = word.indexOf("=");
+    if (eq !== -1) {
+        const entry = lookupFlag(model, state, word.slice(0, eq));
+        if (entry)
+            state.used.add(entry.flag); // inline value travels with the word
+        return;
+    }
+    const entry = lookupFlag(model, state, word);
+    if (entry === undefined)
+        return; // unknown flags are skipped silently
+    state.used.add(entry.flag);
+    if (entry.takesValue)
+        state.pendingValueFlag = entry;
+}
+/** Consume a prior non-flag word: noun, then verb/self-verb, then positionals. */
+function scanCommandWord(word, model, state) {
+    if (state.noun === undefined) {
+        const entry = findNoun(model, word);
+        if (entry === undefined) {
+            state.noun = "unknown";
+            return;
+        }
+        state.noun = entry;
+        // A self-verb-only noun is its own verb; positionals start right away.
+        if (entry.verbs.length === 0 && entry.selfVerb) {
+            state.verb = entry.selfVerb;
+        }
+        return;
+    }
+    if (state.noun === "unknown" || state.verb === "unknown")
+        return;
+    if (state.verb === undefined) {
+        const match = state.noun.verbs.find((verb) => verb.label === word);
+        if (match) {
+            state.verb = match;
+            return;
+        }
+        if (state.noun.selfVerb) {
+            // Not a sub-verb: the word is the self-verb's first positional.
+            state.verb = state.noun.selfVerb;
+            state.positionalsSeen = 1;
+            return;
+        }
+        state.verb = "unknown";
+        return;
+    }
+    // A verb with segment children (a mounted subtree): the word resolves
+    // against the children BEFORE positional counting — a match descends, so
+    // deeper flags/positionals are the child's own; a non-match is terminal.
+    const resolved = knownVerb(state);
+    if (resolved?.children && resolved.children.length > 0) {
+        const child = resolved.children.find((entry) => entry.label === word);
+        if (child) {
+            state.verb = child;
+            state.positionalsSeen = 0;
+            return;
+        }
+        state.verb = "unknown";
+        return;
+    }
+    state.positionalsSeen += 1;
+}
+/** The positional entry at an index (a trailing variadic absorbs the rest). */
+function positionalAt(verb, index) {
+    const direct = verb.positionals[index];
+    if (direct)
+        return direct;
+    const last = verb.positionals[verb.positionals.length - 1];
+    return last?.variadic ? last : undefined;
+}
+/** Flag names offerable now: scoped, de-offered when used and not repeatable. */
+function offeredFlagNames(model, state) {
+    return flagScope(model, state)
+        .filter((entry) => entry.repeatable || !state.used.has(entry.flag))
+        .map((entry) => entry.flag);
+}
+/** Classify the current word against the scanned state (rules 1–7). */
+function classify(current, model, state) {
+    const pending = state.pendingValueFlag;
+    if (pending) {
+        // bash `=` wordbreaks: `--flag =` completes an empty value, `--flag = v`
+        // arrives as a leading-`=` partial in some shells.
+        const partial = current === "="
+            ? ""
+            : current.startsWith("=")
+                ? current.slice(1)
+                : current;
+        return {
+            context: {
+                kind: "flag-value",
+                flag: pending.flag,
+                source: pending.source,
+            },
+            partial,
+        };
+    }
+    if (!state.sawDashDash && current.startsWith("--")) {
+        const eq = current.indexOf("=");
+        if (eq !== -1) {
+            const entry = lookupFlag(model, state, current.slice(0, eq));
+            if (entry?.takesValue) {
+                return {
+                    context: {
+                        kind: "flag-value",
+                        flag: entry.flag,
+                        source: entry.source,
+                    },
+                    partial: current.slice(eq + 1),
+                };
+            }
+        }
+    }
+    if (!state.sawDashDash && current.startsWith("-")) {
+        return {
+            context: { kind: "flag-name", flags: offeredFlagNames(model, state) },
+            partial: current,
+        };
+    }
+    if (state.noun === undefined) {
+        return { context: { kind: "noun" }, partial: current };
+    }
+    if (state.noun === "unknown") {
+        return {
+            context: { kind: "nothing", reason: "unknown noun" },
+            partial: current,
+        };
+    }
+    if (state.verb === "unknown") {
+        return {
+            context: { kind: "nothing", reason: "unknown verb" },
+            partial: current,
+        };
+    }
+    if (state.verb === undefined) {
+        return {
+            context: { kind: "verb", noun: state.noun.noun },
+            partial: current,
+        };
+    }
+    const positional = positionalAt(state.verb, state.positionalsSeen);
+    if (positional === undefined) {
+        return {
+            context: { kind: "nothing", reason: "positionals exhausted" },
+            partial: current,
+        };
+    }
+    return {
+        context: {
+            kind: "positional",
+            name: positional.name,
+            source: positional.source,
+        },
+        partial: current,
+    };
+}
+/**
+ * Parse completion words into a classified request.
+ *
+ * @param words - The command words up to and including the cursor word (the
+ *   last word is the partial being completed, possibly empty). A leading
+ *   word equal to `binName` is stripped.
+ * @param model - The completion model.
+ * @param binName - The program name some shells include as the first word.
+ * @returns The classified context plus the partial.
+ */
+export function parseWords(words, model, binName = BIN_NAME) {
+    const stripped = words[0] === binName ? words.slice(1) : words;
+    const current = stripped[stripped.length - 1] ?? "";
+    const prior = stripped.slice(0, -1);
+    const state = {
+        positionalsSeen: 0,
+        sawDashDash: false,
+        used: new Set(),
+    };
+    for (const word of prior) {
+        if (state.pendingValueFlag) {
+            if (word === "=")
+                continue; // bash wordbreak noise, value still pending
+            state.pendingValueFlag = undefined; // the word is the flag's value
+            continue;
+        }
+        if (!state.sawDashDash && word === "--") {
+            state.sawDashDash = true;
+            continue;
+        }
+        if (!state.sawDashDash && word.startsWith("-")) {
+            scanFlagWord(word, model, state);
+            continue;
+        }
+        scanCommandWord(word, model, state);
+    }
+    return classify(current, model, state);
+}
+//# sourceMappingURL=parse.js.map

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

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

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

@@ -0,0 +1,101 @@
+/**
+ * Candidate ranking and filtering for the completion tiers.
+ *
+ * Two disciplines, deliberately different:
+ * - {@link filterPrefix} for STRUCTURAL sets (nouns, verbs, flag names):
+ *   case-sensitive `startsWith` + lexicographic sort, agreeing with what the
+ *   static scripts' `compgen -W` would produce for the same table.
+ * - {@link rankCandidates} for VALUE sets (enum values, entity names):
+ *   case-insensitive exact > prefix > substring, deduped, tie-broken
+ *   lexicographically, capped — ported from the v1 `rankUriCompletions`.
+ */
+/** Maximum candidates a ranked (value-tier) resolution returns. */
+export const MAX_CANDIDATES = 50;
+/** Match strength of a partial against one candidate, higher is better. */
+const NO_MATCH = 0;
+const FUZZY_MATCH = 1;
+const SUBSTRING_MATCH = 2;
+const PREFIX_MATCH = 3;
+const EXACT_MATCH = 4;
+/** Whether every char of `needle` appears in `hay`, in order (subsequence). */
+function isSubsequence(needle, hay) {
+    if (needle === "")
+        return true;
+    let i = 0;
+    for (const ch of hay) {
+        if (ch === needle[i] && ++i === needle.length)
+            return true;
+    }
+    return false;
+}
+/**
+ * Score a folded candidate against a folded partial under a match strategy.
+ * `prefix` accepts only exact/prefix; `substring` (default) adds substring;
+ * `fuzzy` additionally accepts an in-order subsequence, ranked lowest.
+ */
+function score(candidate, partial, match) {
+    if (candidate === partial)
+        return EXACT_MATCH;
+    if (candidate.startsWith(partial))
+        return PREFIX_MATCH;
+    if (match === "prefix")
+        return NO_MATCH;
+    if (candidate.includes(partial))
+        return SUBSTRING_MATCH;
+    if (match === "fuzzy" && isSubsequence(partial, candidate))
+        return FUZZY_MATCH;
+    return NO_MATCH;
+}
+/**
+ * Rank value candidates for a partial word.
+ *
+ * Exact > prefix > substring > fuzzy; ties broken by the candidate text for
+ * determinism; duplicates dropped; capped at `limit`. Case-insensitive by
+ * default (canonical casing is preserved in the emitted candidate — `bu` →
+ * `Button`). An empty partial matches everything (as a prefix), so it lists the
+ * full set sorted.
+ *
+ * @param candidates - The candidate values.
+ * @param partial - The partial word being completed.
+ * @param limit - Maximum candidates to return.
+ * @param match - Match strategy (default `"substring"`).
+ * @param caseSensitive - Match case-sensitively (default `false`).
+ * @returns Ranked, deduped, capped candidates (original casing preserved).
+ */
+export function rankCandidates(candidates, partial, limit = MAX_CANDIDATES, match = "substring", caseSensitive = false) {
+    const fold = (value) => caseSensitive ? value : value.toLowerCase();
+    const needle = fold(partial);
+    const scored = [];
+    for (const candidate of candidates) {
+        const strength = score(fold(candidate), needle, match);
+        if (strength > NO_MATCH)
+            scored.push({ candidate, strength });
+    }
+    scored.sort((a, b) => b.strength !== a.strength
+        ? b.strength - a.strength
+        : a.candidate.localeCompare(b.candidate));
+    const seen = new Set();
+    const ranked = [];
+    for (const { candidate } of scored) {
+        if (seen.has(candidate))
+            continue;
+        seen.add(candidate);
+        ranked.push(candidate);
+        if (ranked.length >= limit)
+            break;
+    }
+    return ranked;
+}
+/**
+ * Filter a structural set by a case-sensitive prefix.
+ *
+ * @param candidates - The structural candidates (nouns, verbs, flag names).
+ * @param partial - The partial word being completed.
+ * @returns The matches, deduped and sorted lexicographically.
+ */
+export function filterPrefix(candidates, partial) {
+    return [...new Set(candidates)]
+        .filter((candidate) => candidate.startsWith(partial))
+        .sort((a, b) => a.localeCompare(b));
+}
+//# sourceMappingURL=rank.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rank.js","sourceRoot":"","sources":["../../../../src/kernel/completion/rank.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,mEAAmE;AACnE,MAAM,CAAC,MAAM,cAAc,GAAG,EAAE,CAAC;AAEjC,2EAA2E;AAC3E,MAAM,QAAQ,GAAG,CAAC,CAAC;AACnB,MAAM,WAAW,GAAG,CAAC,CAAC;AACtB,MAAM,eAAe,GAAG,CAAC,CAAC;AAC1B,MAAM,YAAY,GAAG,CAAC,CAAC;AACvB,MAAM,WAAW,GAAG,CAAC,CAAC;AAEtB,+EAA+E;AAC/E,SAAS,aAAa,CAAC,MAAc,EAAE,GAAW;IAChD,IAAI,MAAM,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAC/B,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,KAAK,MAAM,EAAE,IAAI,GAAG,EAAE,CAAC;QACrB,IAAI,EAAE,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM;YAAE,OAAO,IAAI,CAAC;IAC7D,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,SAAS,KAAK,CACZ,SAAiB,EACjB,OAAe,EACf,KAAsB;IAEtB,IAAI,SAAS,KAAK,OAAO;QAAE,OAAO,WAAW,CAAC;IAC9C,IAAI,SAAS,CAAC,UAAU,CAAC,OAAO,CAAC;QAAE,OAAO,YAAY,CAAC;IACvD,IAAI,KAAK,KAAK,QAAQ;QAAE,OAAO,QAAQ,CAAC;IACxC,IAAI,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC;QAAE,OAAO,eAAe,CAAC;IACxD,IAAI,KAAK,KAAK,OAAO,IAAI,aAAa,CAAC,OAAO,EAAE,SAAS,CAAC;QACxD,OAAO,WAAW,CAAC;IACrB,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,cAAc,CAC5B,UAA6B,EAC7B,OAAe,EACf,QAAgB,cAAc,EAC9B,QAAyB,WAAW,EACpC,gBAAyB,KAAK;IAE9B,MAAM,IAAI,GAAG,CAAC,KAAa,EAAU,EAAE,CACrC,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC;IAC9C,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;IAE7B,MAAM,MAAM,GAA8C,EAAE,CAAC;IAC7D,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;QACvD,IAAI,QAAQ,GAAG,QAAQ;YAAE,MAAM,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,CAAC;IAChE,CAAC;IAED,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACnB,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,QAAQ;QACvB,CAAC,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ;QACzB,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,CAC3C,CAAC;IAEF,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,KAAK,MAAM,EAAE,SAAS,EAAE,IAAI,MAAM,EAAE,CAAC;QACnC,IAAI,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC;YAAE,SAAS;QAClC,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACpB,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACvB,IAAI,MAAM,CAAC,MAAM,IAAI,KAAK;YAAE,MAAM;IACpC,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAC1B,UAA6B,EAC7B,OAAe;IAEf,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC;SAC5B,MAAM,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;SACpD,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;AACxC,CAAC"}

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

@@ -0,0 +1,100 @@
+/**
+ * Resolve a classified completion request into candidates.
+ *
+ * Structural contexts (noun, verb, flag-name) filter their model-derived
+ * tables with the case-sensitive {@link filterPrefix} — the same offers the
+ * static scripts inline. Value contexts (flag-value, positional) go through
+ * the source table: enum values and entity names are ranked case-insensitively
+ * and capped; `files` returns nothing (the static scripts complete files
+ * natively — the resolver never lists the filesystem); `none` and unknown
+ * (reserved) kinds return nothing.
+ *
+ * Injection safety, runtime gate: every value-tier candidate must match the
+ * same {@link SAFE_TOKEN_RE} allowlist the emit-time gate enforces — hostile
+ * names from an index file are dropped before they can reach a shell buffer.
+ * Structural candidates were already asserted safe when the model was built.
+ */
+import { findNoun, SAFE_TOKEN_RE } from "./model.js";
+import { filterPrefix, MAX_CANDIDATES, rankCandidates } from "./rank.js";
+/**
+ * Write a completion debug line to stderr when `PRAGMA_COMPLETE_DEBUG=1`.
+ * Silent otherwise — stdout is reserved for candidates, and stderr must not
+ * leak into shell buffers during normal completion.
+ *
+ * @param message - The debug message (prefixed with `[complete]`).
+ * @note Impure — reads the environment, writes stderr.
+ */
+export function completionDebug(message) {
+    if (process.env.PRAGMA_COMPLETE_DEBUG === "1") {
+        process.stderr.write(`[complete] ${message}\n`);
+    }
+}
+/** Drop candidates that fail the shell-safety allowlist (with a debug note). */
+function sanitize(candidates) {
+    const safe = candidates.filter((candidate) => SAFE_TOKEN_RE.test(candidate));
+    if (safe.length !== candidates.length) {
+        completionDebug(`dropped ${candidates.length - safe.length} unsafe candidate(s)`);
+    }
+    return safe;
+}
+/** Resolve a value-tier source into ranked, sanitized candidates. */
+async function resolveSource(source, partial, env) {
+    switch (source.kind) {
+        case "values":
+            return rankCandidates(sanitize(source.values), partial);
+        case "names": {
+            let names;
+            try {
+                names = await env.names(source.ref);
+            }
+            catch (error) {
+                // The seam contract is never-throw; degrade anyway, never break TAB.
+                completionDebug(`name source read failed: ${error instanceof Error ? error.message : String(error)}`);
+                return [];
+            }
+            return rankCandidates(sanitize(names), partial, MAX_CANDIDATES, source.match, source.caseSensitive);
+        }
+        case "files":
+            // Consumer rule: files are completed natively by the shell scripts
+            // (compgen -f / _files / fish -rF); the resolver offers nothing.
+            return [];
+        case "none":
+            return [];
+        default: {
+            // Reserved kinds ({kind:"query"} and future ones) are not in the union;
+            // if one arrives at runtime it resolves to nothing, with a reason.
+            const kind = source.kind;
+            completionDebug(`nothing: reserved completion kind "${kind}"`);
+            return [];
+        }
+    }
+}
+/**
+ * Resolve a parsed completion request against the model and environment.
+ *
+ * @param request - The classified context plus partial from `parseWords`.
+ * @param model - The completion model.
+ * @param env - The completion environment (the entity seam).
+ * @returns Matching candidates, ranked/filtered per tier; `[]` when there is
+ *   nothing to offer.
+ */
+export async function resolveRequest(request, model, env) {
+    const { context, partial } = request;
+    switch (context.kind) {
+        case "noun":
+            return filterPrefix(model.nouns.map((entry) => entry.noun), partial);
+        case "verb": {
+            const noun = findNoun(model, context.noun);
+            return filterPrefix((noun?.verbs ?? []).map((verb) => verb.label), partial);
+        }
+        case "flag-name":
+            return filterPrefix(context.flags, partial);
+        case "flag-value":
+        case "positional":
+            return resolveSource(context.source, partial, env);
+        case "nothing":
+            completionDebug(`nothing: ${context.reason}`);
+            return [];
+    }
+}
+//# sourceMappingURL=resolve.js.map

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

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