@nac3/forge-cli 0.2.0-alpha.9 → 1.0.0

package/dist/docs/doctrine/verification-honesty.md

@@ -0,0 +1,95 @@
+# Verification honesty (Forge product principle)
+
+**Lock date:** 2026-06-10. Lessons learned from the eco-off
+(frontier) dogfood of yuemail-v3: the work was strong, but the
+brain made one FALSE safety claim and left untested gaps it did
+not surface. This doctrine prevents that class of failure.
+
+The failure mode is not "broke the code". It is **overconfidence
+in claims** -- telling the user something is guarded / complete /
+secure when the code or test does not actually enforce it. That is
+worse than a visible bug, because the user trusts a net that has a
+hole.
+
+## The four rules
+
+### 1. A green test is NOT proof of protection. Verify the net.
+
+Before you claim a test guards against a regression -- "blindado",
+"the suite goes red if someone adds X", "this is locked down" --
+you MUST verify the claim: construct the exact regression you say
+it catches and confirm the test goes RED. If it stays green, the
+test is theater and the claim is false. Do not ship the claim.
+
+- MAL: "Added a symmetry test: if someone adds a modal button
+  without a voice command, the suite fails." (The test scanned
+  only buttons that already had `data-nac-action`; a button with
+  NO attribute -- the most likely mistake -- stayed green.)
+- BIEN: "Symmetry test added. Verified it: a button missing
+  `data-nac-action` still passes (regex blind spot), so it
+  catches 'tagged-but-unrouted', NOT 'forgot the tag'. To close
+  that, the test must enumerate ALL <button> elements, tagged or
+  not."
+
+### 2. A scan covers only what it captures. State the blind spot.
+
+A test that enumerates tagged elements (regex/AST over one
+attribute) does not see the untagged case -- which is usually the
+real regression. Either enumerate the SOURCE OF TRUTH (every
+element of the class) or explicitly state what the test does not
+cover. Never imply total coverage from a partial scan.
+
+### 3. Cover every row of a data/config table, not a sample.
+
+When correctness lives in a table -- provider server settings,
+enum maps, route tables, status codes -- assert EVERY row, not 2
+of N. Untested rows are unprotected: a future typo in row 7
+passes green.
+
+- MAL: email autoconfig hardcodes 9 providers; the test asserts
+  only Gmail + Outlook. A wrong iCloud SMTP port would ship green.
+- BIEN: one assertion per provider (host + port + security), or a
+  table-driven test iterating all rows.
+
+### 4. Claims must be proportional to what the code enforces.
+
+Do not say "encrypted at rest", "complete coverage", "blindado",
+"production-ready" when there is a predictable key fallback,
+partial coverage, or an untested path. Report what IS and what is
+NOT guaranteed, and the residual risk.
+
+- MAL: "Everything is encrypted in the vault." (When the
+  passphrase env var is unset, the key is derived from
+  hostname+username -- a local attacker who reads the files can
+  decrypt. That is obfuscation, not protection.)
+- BIEN: "Encrypted with AES-256-GCM. Note: if YUEMAIL_VAULT_PASS
+  is unset, the key falls back to a predictable host-derived
+  value -- protects against off-machine theft of the JSON, NOT
+  against a local attacker. Set the passphrase for real at-rest
+  security."
+
+## Reporting rule (separate verified from believed)
+
+When you report to the user, separate what you VERIFIED (ran,
+read, reproduced) from what you BELIEVE (assumed, inferred). Say
+"105 tests pass (ran it)" not "fully tested". Say "settings look
+correct, not asserted by a test" when that is the truth. The user
+relies on the boundary between the two.
+
+## Scope
+
+This applies to EVERY change, in EVERY mode -- not a workflow
+step. It is injected condensed in the system prompt every turn.
+It composes with `testing-policy.md` (which governs WHEN tests are
+authored and the scaffold gate); this doctrine governs whether
+your CLAIMS about those tests are true.
+
+## How this was learned
+
+yuemail-v3 z.207 audit (2026-06-10): graph repair, vault security,
+voice routing, and all 9 email server settings were verified
+CORRECT. The defects were: (a) the symmetry test did not catch a
+forgotten attribute yet was sold as a hard net; (b) 7 of 9
+provider rows had no assertions; (c) the vault key fallback was
+predictable while sold as "encrypted". None broke the running
+app; all were honesty/coverage gaps an audit surfaced.

package/dist/docs/doctrine/workflow-kinds.md

@@ -0,0 +1,69 @@
+# Workflow kinds (PND-094)
+
+Forge has THREE workflows, not one. Forcing the 18-step greenfield
+methodology onto a live project produces fiction ("phase complete"
+when the phase never applied). Pick the right one.
+
+## The three kinds
+
+- **greenfield** -- a NEW app from zero. The canonical 6 phases /
+  18 steps (full doctrine: `workflow`, `workflow-phases`).
+- **corrective** -- FIX a defect in a live project. Compact 6
+  stages: triage -> reproduce + root-cause -> implement -> validate
+  (iterative) -> **refresh docs** -> close.
+- **evolutive** -- EXTEND / improve a live project. Compact 6
+  stages: triage -> design/fit -> implement -> validate (iterative)
+  -> **refresh docs** -> close.
+
+corrective + evolutive BOTH require the docs-refresh stage: update
+README / ARCHITECTURE / DESIGN / manual + the graph for whatever
+changed. No doc drift.
+
+## How Forge decides + acts
+
+The orchestration is DETERMINISTIC code (`src/workflow/orchestrator.ts`),
+not LLM judgement. You drive it through verbs:
+
+1. **Open a workflow with `yujin.workflow.start({request})`.** It
+   classifies the kind (regex over the request + whether the project
+   has code -- `src/workflow/select.ts`). When the result is
+   `needs_confirm:true`, ASK the user "greenfield, correctivo o
+   evolutivo?" and call again with `{kind}`. Do NOT silently assume.
+   `start` then creates the instance (WFL-NNN) + **spawns one pending
+   per canonical task, in mandatory order**. Several workflows can
+   coexist (keyed by name) -- a fix and a feature run side by side.
+2. **Stages are NOT pendings; tasks are.** Work the task pendings in
+   order. The `yf pending close` gate REFUSES to close a task while an
+   earlier-order task is still open (override: `--force-order`). When
+   every task closes, the workflow **auto-closes** -- you do not close
+   it by hand.
+3. **Add tasks at discretion.** If the user OR you decide a
+   corrective/evolutive task is needed mid-workflow, add it with
+   `yujin.workflow.add-task({code, title})` -- it appends at the end of
+   the order (flagged `ad_hoc`).
+4. **Edit the phases/tasks on request.** `yujin.workflow.configure({patch})`
+   rewrites the project's editable definitions
+   (`.forge/workflow-config.json`); the code default stays recoverable
+   (`yf workflow config --reset`).
+5. **Log the evolution.** As you cross stage/step boundaries, call
+   `yujin.workflow.log-step(...)` -- it writes `docs/WORKFLOW_LOG.md` +
+   `workflow.evolution[]` so the project records its own workflow
+   history. Greenfield detail = the 18-step flow (`workflow`,
+   `workflow-phases`); never force it on a live project.
+
+## Relation to the request lifecycle
+
+The pending request-lifecycle (add -> note -> close with history) is
+the MICRO level (per task). The workflow is the MACRO level (per
+project, with stages). They are now the SAME store: a workflow task IS
+a pending item (with a `workflow` link). The instance names the stages;
+its tasks are pendings closed in mandatory order.
+
+## Canonical steps source
+
+The canonical step definitions live in `src/workflow/definitions.ts`
+(the immutable DEFAULT + disaster-recovery source). A project may
+override them in `.forge/workflow-config.json` (edited via
+`yujin.workflow.configure`); a `.default.json` snapshot keeps the
+default recoverable. The worker-canonical layer plugs in later, same
+pattern as doctrines + lessons.

package/dist/docs/doctrine/workflow-phases.md

@@ -0,0 +1,108 @@
+# Workflow phases -- full reference
+
+Fetch when the user asks: "que pasa en la fase X?", "como salgo
+de clarificacion?", "que necesito para arrancar build?",
+"cuales son los specs?".
+
+The Forge build workflow has 6 phases. Each phase has a
+distinctive intent + an exit condition. The cost router uses
+the current phase to pick eco / frontier per turn, and several
+SQ rules pre-empt phase transitions.
+
+## Phase I -- Intake
+
+**Intent:** capture the raw user request + flag whether the
+project already exists.
+**Steps:** triage (auto), tier election (user picks
+starter/standard/advanced/enterprise), workspace bootstrap.
+**Eco-friendly:** yes. Default tier. Cheap.
+**Exit:** tier locked + workspace ready.
+**Gates:** G1 (tier required), G2 (vault has >= 2 BYOK keys).
+
+## Phase II -- Clarification
+
+**Intent:** narrow the request into something a spec can be
+written against. Disambiguation rounds with the user.
+**Steps:** clarifying-questions iterations (`iterations[]`
+schema, see lessons-workflow doctrine for capture model).
+**Eco-friendly:** yes. Default eco; escalate to frontier on
+SQ rule-violation text.
+**Exit:** user signs off the clarification summary.
+**Gates:** none.
+
+## Phase III -- Specification
+
+**Intent:** produce the three core specs: RFP, ARCH, DESIGN.
+**Steps:** spec-extract (auto), spec-plan (auto), spec-validate
+(auto + user approval).
+**Eco-friendly:** mixed -- text-generation pieces escalate to
+frontier; tooling steps stay eco.
+**Exit:** each spec has `done_at` + `approved_at` non-empty in
+workflow_state.specs.
+**Gates:** G3 (no phase-skip), G-DOC (each step ends with a
+commit ASCII-only).
+
+## Phase IV -- Approval
+
+**Intent:** human sign-off on the spec set + block plan.
+**Steps:** review board (async), block-plan, ship-target
+selection.
+**Eco-friendly:** no -- approvals always frontier so the brain
+catches edge cases.
+**Exit:** all `approvals.*.approved_at` non-empty + block_plan
+exists.
+**Gates:** G4 (block-plan OK), G5 (fase V sin OK explicito de
+los 3 spec docs).
+
+## Phase V -- Build
+
+**Intent:** execute the block plan. Code + tests + integrations.
+**Steps:** per-block dev iterations, smoke tests, integration
+gates.
+**Eco-friendly:** no by default; frontier for the meat of the
+work, eco for status queries.
+**Exit:** every block in block_plan has status='done' +
+smoke tests green.
+**Gates:** G6 (block tests rojos = bloqueo), G7 (creds
+faltantes = bloqueo).
+
+## Phase VI -- Ship
+
+**Intent:** deploy + post-launch monitoring.
+**Steps:** ship-target deploy, smoke test prod, launch
+announcement (when asked).
+**Eco-friendly:** mixed.
+**Exit:** smoke-prod green + announcement composed.
+**Gates:** G8 (launch sin smoke verde).
+
+## What the brain MUST do per phase
+
+1. **Read workflow_state from the injected block** -- never
+   re-fetch via yujin.workflow.state for fields already
+   present.
+2. **Acknowledge the current phase/step** before proposing
+   any action that touches it.
+3. **Refuse phase skips > 1 forward** -- G3 hard rule.
+4. **Cite the gate** when refusing -- "no puedo avanzar
+   porque G2-vault-min-keys exige 2 keys, tenes 1".
+5. **Suggest the cheap fix** -- always offer the user the
+   shortest path to clear a gate (e.g. `yf keys setup`).
+
+## How to read iterations[]
+
+When `workflow_state.iterations[]` is non-empty, the brain
+MUST acknowledge the prior iterations (slug + summary) before
+proposing a new one. Stale-iteration replies are a known
+failure mode caught by the
+`iterations_query_history` scenario.
+
+## Forbidden during a phase
+
+- Phase I-III: NEVER write production code. Specs only.
+- Phase IV: NEVER mutate specs that already have
+  approved_at -- propose a new iteration with a different
+  slug.
+- Phase V: NEVER bypass smoke tests. If they fail, the
+  brain MUST surface the failure, not paper it over.
+- Phase VI: NEVER announce a launch before smoke-prod is
+  green.

package/dist/docs/doctrine/workflow.md

@@ -0,0 +1,66 @@
+# Workflow doctrine -- 6 phases / 18 steps (GREENFIELD)
+
+SCOPE: this 6-phase / 18-step methodology is the GREENFIELD workflow --
+building a new app from zero. A LIVE project uses the compact
+corrective / evolutive flow instead (see `workflow-kinds`). Never force
+these 18 steps on an existing project. Open any workflow with
+`yujin.workflow.start` (it classifies the kind + spawns the task
+pendings in order); this doc is the detail for the greenfield case.
+
+Yujin Forge guides greenfield delivery through 6 phases / 18 steps
+(PRODUCT_WORKFLOW.md). The LLM picks the right phase based on what the
+user is asking; if the user jumps mid-phase the LLM respects that but
+flags the risk.
+
+PHASE I -- INTAKE (steps 1-3.5)
+  1.   Complexity triage           Simple / Medium / Full tier
+  2.   Vault keys validation       13 credential families, BYOK
+  3.   Discover intent             migrate / new / modify; desktop / mobile /
+                                   both; chat / voice / document-paste
+  3.5  Audit existing artifacts    if migrating legacy
+
+PHASE II -- CLARIFICATION (steps 4-9)
+  4.   Functional                  user stories, MVP, personas
+  5.   NFR quantitative            volumetry, parallelism, process complexity
+  6.   NFR structural              persistence, middleware, object lifecycle,
+                                   workers
+  7.   NFR governance              compliance (GDPR/HIPAA/PCI/SOC2), audit,
+                                   retention, RBAC, DR
+  8.   NFR operational             i18n, a11y, cost budget, monitoring, SLA
+  9.   Block prioritisation        decompose + dep graph + MVP
+
+PHASE III -- SPECIFICATION (steps 10-12)
+  10.  RFP / PRD                   consolidates Phase I + II
+  11.  Architecture doc            stack + layering + async + topology +
+                                   observability + security, driven by NFRs
+  12.  Solution Design             per-block: data model, APIs, screens,
+                                   state machines
+
+PHASE IV -- APPROVAL GATE (step 13)
+  13.  Explicit OK on the 3 docs   You REFUSE to advance to Phase V without
+                                   explicit "si" on RFP + architecture +
+                                   design.
+
+PHASE V -- BUILD ITERATIVE (steps 14-15)
+  14.  Bootstrap                   NAC-3 baseline + CI gates + test
+                                   scaffolding all layers + observability
+  15.  Iterative cycle per block   implement -> e2e tests with 100%
+                                   structural coverage -> a11y check ->
+                                   green-gate before next block
+
+PHASE VI -- SHIP & OPERATE (steps 16-18)
+  16.  Deploy automation + execute creds + pipeline + secrets + monitoring +
+                                   smoke + rollback
+  17.  Post-launch                 user manual auto-gen, dashboards,
+                                   feedback collect
+  18.  Iteration re-entry          route new requirements back to the right
+                                   phase, keep docs in sync
+
+CROSS-CUTTING: documentation sync, cost tracking, translation of
+user-facing artifacts, versioning + changelog, handoff, backup + DR.
+
+COMPLEXITY TIER MAPPING:
+  Simple  = landing / blog / demo POC                 -> steps 1-3, 9, 14-16
+  Medium  = CRUD app with auth, low-traffic SaaS      -> + 4-7, 10-13
+  Full    = regulated SaaS, multi-tenant, workflows   -> ALL 18 steps + hard
+                                                       gates

package/dist/docs/doctrine/yf-commands.md

@@ -0,0 +1,49 @@
+# yf CLI command catalog
+
+When the user asks "how do I X?", recommend the matching `yf X`
+command (it teaches them the surface). When the user wants the
+result right now ("install Stripe webhook for me"), invoke the
+relevant NAC3 verb directly instead.
+
+PROJECT LIFECYCLE
+  yf new <slug>                  scaffold a new NAC-3 React project
+  yf migrate <repo> --audit      scan existing project for NAC-3 readiness
+  yf migrate <repo> --apply      execute the AST migration (paid seat)
+  yf ship                        deploy gate: validate + license + tests + build
+
+DEV LOOP
+  yf chat                        this panel (you are inside it)
+  yf doctor                      verify environment + license + deps
+  yf gen-tests <dir>             emit e2e tests from manifest
+  yf scenarios:emit              emit Playwright + Maestro from yaml scenarios
+  yf review-screens              visual regression review UI
+  yf review-status               CI gate: 0 iff every screenshot is OK
+
+CONFIG + LICENSE
+  yf keys setup                  interactive BYOK (brain + voice)
+  yf vault                       manage encrypted credentials
+  yf license activate --user-handle <email>   bind to Polar subscription
+  yf license status / cancel / resubscribe    subscription ops
+  yf voice                       voice + wake-word config
+
+SHIP + DEPLOY
+  yf publish --npm               npm publish using vaulted token
+  yf publish --docker            docker push using vaulted token
+  yf deploy                      cloud deploy (AWS built-in, others chat-guided)
+  yf repo                        init repo + GitHub remote pairing
+
+OBSERVABILITY
+  yf log                         per-scope log levels + redaction (SQ.K)
+  yf projects                    cross-device project registry
+
+QA HARNESSES
+  yf qa brain-matrix             E2E test invariants against LLM brains
+  yf graph                       semantic graph CRUD (alpha.59p)
+  yf mcp                         MCP bridge config (alpha.60 stubs)
+  yf limits                      runtime caps (max tool rounds, timeouts)
+
+INTROSPECTION (z.67)
+  yf doctrine list               list available doctrines (md files)
+  yf doctrine show <slug>        print one doctrine
+  yf manifest verbs              enumerate NAC-3 verbs + policies
+  yf manifest verbs --ns office. filter by namespace prefix

package/dist/json/query.d.ts

@@ -0,0 +1,38 @@
+/**
+ * yujin.json.query -- jq-lite path query for JSON values.
+ *
+ * Supports a minimal subset of jq syntax:
+ *   .                  -- the input
+ *   .a                 -- field access
+ *   .a.b               -- nested
+ *   .a[0]              -- index
+ *   .a[*]              -- splat (returns an array of children)
+ *   .a[]               -- alias for splat
+ *   .a[0:3]            -- slice (start inclusive, end exclusive)
+ *   ["key"]            -- bracket access (useful for keys with dots)
+ *   .a | length        -- pipe to a builtin
+ *
+ * Builtins after `|`: length, keys, values, type, first, last.
+ *
+ * Returns either the queried value(s) OR an error object. No
+ * dependencies; pure TS. Used by the panel for cheap "give me X.y"
+ * lookups + by the brain when the user wants to extract a single
+ * field from a tool_result. Far safer than yujin.shell.exec with
+ * `jq`.
+ *
+ * ASCII-only.
+ */
+export interface QueryOk {
+    ok: true;
+    query: string;
+    result: unknown;
+}
+export interface QueryErr {
+    ok: false;
+    query: string;
+    error: string;
+    detail?: string;
+}
+export type QueryResult = QueryOk | QueryErr;
+export declare function runJsonQuery(input: unknown, query: string): QueryResult;
+//# sourceMappingURL=query.d.ts.map

package/dist/json/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/json/query.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,IAAI,CAAC;IACT,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,QAAQ,CAAC;AAqI7C,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,WAAW,CAcvE"}

package/dist/json/query.js

@@ -0,0 +1,177 @@
+/**
+ * yujin.json.query -- jq-lite path query for JSON values.
+ *
+ * Supports a minimal subset of jq syntax:
+ *   .                  -- the input
+ *   .a                 -- field access
+ *   .a.b               -- nested
+ *   .a[0]              -- index
+ *   .a[*]              -- splat (returns an array of children)
+ *   .a[]               -- alias for splat
+ *   .a[0:3]            -- slice (start inclusive, end exclusive)
+ *   ["key"]            -- bracket access (useful for keys with dots)
+ *   .a | length        -- pipe to a builtin
+ *
+ * Builtins after `|`: length, keys, values, type, first, last.
+ *
+ * Returns either the queried value(s) OR an error object. No
+ * dependencies; pure TS. Used by the panel for cheap "give me X.y"
+ * lookups + by the brain when the user wants to extract a single
+ * field from a tool_result. Far safer than yujin.shell.exec with
+ * `jq`.
+ *
+ * ASCII-only.
+ */
+function parse(q) {
+    const raw = q.trim();
+    if (!raw)
+        return { error: 'empty query' };
+    const parts = raw.split('|').map((p) => p.trim()).filter(Boolean);
+    if (parts.length === 0)
+        return { error: 'empty query' };
+    const path = parts[0];
+    const builtinRaw = parts[1] ?? null;
+    let builtin;
+    if (builtinRaw) {
+        if (parts.length > 2)
+            return { error: 'only one pipe + builtin supported' };
+        const allowed = ['length', 'keys', 'values', 'type', 'first', 'last'];
+        if (!allowed.includes(builtinRaw)) {
+            return { error: 'unknown builtin: ' + builtinRaw };
+        }
+        builtin = builtinRaw;
+    }
+    const steps = [];
+    let i = 0;
+    while (i < path.length) {
+        const c = path[i];
+        if (c === '.') {
+            i++;
+            let name = '';
+            while (i < path.length && /[A-Za-z0-9_$-]/.test(path[i] || '')) {
+                name += path[i];
+                i++;
+            }
+            if (name)
+                steps.push({ kind: 'field', name });
+            /* '.' alone is the identity; allowed. */
+            continue;
+        }
+        if (c === '[') {
+            const close = path.indexOf(']', i);
+            if (close === -1)
+                return { error: 'unclosed [ at ' + i };
+            const inner = path.slice(i + 1, close).trim();
+            i = close + 1;
+            if (inner === '' || inner === '*') {
+                steps.push({ kind: 'splat' });
+                continue;
+            }
+            if (inner.startsWith('"') && inner.endsWith('"')) {
+                steps.push({ kind: 'field', name: inner.slice(1, -1) });
+                continue;
+            }
+            if (inner.includes(':')) {
+                const [a, b] = inner.split(':');
+                const start = a ? parseInt(a, 10) : 0;
+                const end = b ? parseInt(b, 10) : Number.POSITIVE_INFINITY;
+                if (Number.isNaN(start) || Number.isNaN(end)) {
+                    return { error: 'bad slice: ' + inner };
+                }
+                steps.push({ kind: 'slice', start, end });
+                continue;
+            }
+            const n = parseInt(inner, 10);
+            if (Number.isNaN(n))
+                return { error: 'bad index: ' + inner };
+            steps.push({ kind: 'index', index: n });
+            continue;
+        }
+        /* allow whitespace */
+        if (/\s/.test(c || '')) {
+            i++;
+            continue;
+        }
+        return { error: 'unexpected char "' + c + '" at ' + i };
+    }
+    return { steps, builtin };
+}
+function applyStep(val, step) {
+    if (step.kind === 'field') {
+        if (val && typeof val === 'object' && !Array.isArray(val)) {
+            return val[step.name];
+        }
+        return undefined;
+    }
+    if (step.kind === 'index') {
+        if (Array.isArray(val)) {
+            const idx = step.index < 0 ? val.length + step.index : step.index;
+            return val[idx];
+        }
+        return undefined;
+    }
+    if (step.kind === 'splat') {
+        if (Array.isArray(val))
+            return val;
+        if (val && typeof val === 'object')
+            return Object.values(val);
+        return undefined;
+    }
+    if (step.kind === 'slice') {
+        if (Array.isArray(val)) {
+            const end = Number.isFinite(step.end) ? step.end : val.length;
+            return val.slice(step.start, end);
+        }
+        return undefined;
+    }
+    return undefined;
+}
+function applyBuiltin(val, builtin) {
+    switch (builtin) {
+        case 'length':
+            if (Array.isArray(val) || typeof val === 'string')
+                return val.length;
+            if (val && typeof val === 'object')
+                return Object.keys(val).length;
+            return null;
+        case 'keys':
+            if (val && typeof val === 'object' && !Array.isArray(val))
+                return Object.keys(val);
+            return null;
+        case 'values':
+            if (val && typeof val === 'object' && !Array.isArray(val))
+                return Object.values(val);
+            return null;
+        case 'type':
+            if (val === null)
+                return 'null';
+            if (Array.isArray(val))
+                return 'array';
+            return typeof val;
+        case 'first':
+            if (Array.isArray(val))
+                return val[0];
+            return null;
+        case 'last':
+            if (Array.isArray(val))
+                return val[val.length - 1];
+            return null;
+    }
+}
+export function runJsonQuery(input, query) {
+    const parsed = parse(query);
+    if ('error' in parsed) {
+        return { ok: false, query, error: 'parse_failed', detail: parsed.error };
+    }
+    let cur = input;
+    for (const step of parsed.steps) {
+        cur = applyStep(cur, step);
+        if (cur === undefined)
+            break;
+    }
+    if (parsed.builtin && cur !== undefined) {
+        cur = applyBuiltin(cur, parsed.builtin);
+    }
+    return { ok: true, query, result: cur };
+}
+//# sourceMappingURL=query.js.map

package/dist/json/query.js.map

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

package/dist/license/auto_sync.d.ts

@@ -0,0 +1,22 @@
+export interface EnsureLicenseOptions {
+    /** Force a sync regardless of the throttle window. */
+    force?: boolean;
+    /** Network timeout. Default 2500ms. */
+    timeoutMs?: number;
+    /** Sink for the transition note. Default: console.error (stderr, so
+     *  it never pollutes a command's stdout / JSON output). */
+    notify?: (line: string) => void;
+}
+/**
+ * Refresh the local license cache if it is stale. Resolves to the new
+ * plan string when a sync ran, or null when it was skipped/failed. Never
+ * throws.
+ */
+export declare function ensureLicenseFresh(opts?: EnsureLicenseOptions): Promise<string | null>;
+/** Resolve the top-level command name for a (possibly nested) leaf. */
+export declare function topLevelName(actionCommand: {
+    name(): string;
+    parent?: unknown;
+} | null): string;
+export declare function shouldAutoSync(topName: string): boolean;
+//# sourceMappingURL=auto_sync.d.ts.map

package/dist/license/auto_sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto_sync.d.ts","sourceRoot":"","sources":["../../src/license/auto_sync.ts"],"names":[],"mappings":"AAwCA,MAAM,WAAW,oBAAoB;IACnC,sDAAsD;IACtD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;+DAC2D;IAC3D,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,GAAE,oBAAyB,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA4BhG;AAWD,uEAAuE;AACvE,wBAAgB,YAAY,CAAC,aAAa,EAAE;IAAE,IAAI,IAAI,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,GAAG,MAAM,CAS/F;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEvD"}