@vincentt-xr/cli 0.7.0 → 0.9.0

package/dist/dx/command.js

@@ -1,4 +1,5 @@
 import { findClusters, rankClusters } from "./clusters.js";
+import { enablementLine } from "./enablement.js";
 import { journalEnabled, journalPath, readJournal } from "./journal.js";
 import { buildReport, renderPayload } from "./send.js";
 const DEFAULT_DAYS = 7;
@@ -7,12 +8,19 @@ export function parseDxOptions(args) {
     const raw = i !== -1 ? Number(args[i + 1]) : NaN;
     const n = args.indexOf("--note");
     const note = n !== -1 ? args[n + 1] : undefined;
+    // Positional, and read only from the slot right after the verb: `--note enable`
+    // is a note, not a subcommand. Deliberately NOT flags — a flag form
+    // (`--enable`) would be one more thing an agent can append to a command it is
+    // already running, which is the shape this whole gate exists to refuse.
+    const sub = args[0] === "dx" ? args[1] : args[0];
     return {
         days: Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_DAYS,
         json: args.includes("--json"),
         send: args.includes("--send"),
         yes: args.includes("--yes"),
         note: note !== undefined && !note.startsWith("-") ? note : undefined,
+        enable: sub === "enable",
+        disable: sub === "disable",
     };
 }
 function withinDays(entries, days, now) {
@@ -60,8 +68,20 @@ export function dxCommand(deps, options) {
     }
     const entries = withinDays(all, options.days, deps.now());
     const clusters = rankClusters(findClusters(entries));
+    const enablement = deps.enablement?.() ?? { enabled: false };
     if (options.json) {
-        deps.print(JSON.stringify({ window: `${options.days}d`, runs: entries.length, clusters }, null, 2));
+        // The JSON object carries enablement as FIELDS because --json is the path an
+        // AGENT reads, and an agent that can send unattended should be able to see
+        // that it can.
+        deps.print(JSON.stringify({
+            window: `${options.days}d`,
+            runs: entries.length,
+            clusters,
+            dxSendEnabled: enablement.enabled,
+            ...(enablement.enabled && enablement.at !== undefined
+                ? { dxSendEnabledAt: enablement.at }
+                : {}),
+        }, null, 2));
         return 0;
     }
     deps.print(`${entries.length} runs in the last ${options.days} days.`);
@@ -87,18 +107,102 @@ export function dxCommand(deps, options) {
     // and a claim only made on some runs is one a reader cannot rely on.
     deps.print("");
     deps.print(`Journal: ${deps.path()} (local only, never sent)`);
+    // Beside it, and ONLY when enabled. Enablement is durable and has no expiry, so
+    // this line is the mitigation rather than a status decoration; printing an
+    // `off` counterpart on every run is how it would get skimmed past.
+    const line = enablementLine(enablement, deps.now());
+    if (line !== undefined)
+        deps.print(line);
     return 0;
 }
 /** Wire the command to the real journal. */
-export function runDx(args, print) {
+export function runDx(args, print, enablement = () => ({ enabled: false })) {
     return dxCommand({
         entries: readJournal,
         print,
         now: () => Date.now(),
         enabled: () => journalEnabled(),
         path: journalPath,
+        enablement,
     }, parseDxOptions(args));
 }
+/** A date a human can read, for the sunset refusal. */
+function sunsetDate(sunset) {
+    return new Date(sunset).toISOString().slice(0, 10);
+}
+/**
+ * `vincentt dx enable` — grant this machine durable permission to send DX reports
+ * without asking first.
+ *
+ * The TTY requirement is a SPEED BUMP, NOT A BOUNDARY, and is written down as
+ * such so a later reader does not build on a guarantee that is not there. It
+ * stops the reflex — an agent that meets a prompt, infers there must be a way
+ * past it, and tries the obvious thing. It does not stop a caller that allocates
+ * a PTY or writes config.json directly.
+ *
+ * The refusal path writes NOTHING. Not "writes the same bytes back" — nothing at
+ * all: this file holds the PAT, and a refusal that round-trips the config through
+ * a write can lose the credential if it dies mid-write.
+ */
+export async function dxEnableCommand(deps, sunset) {
+    if (deps.now() >= sunset) {
+        deps.print("");
+        deps.print(`  Unattended DX submission ended on ${sunsetDate(sunset)} and can no longer be enabled.`);
+        deps.print("  Reports can still be sent from your own terminal.");
+        deps.print("");
+        return 1;
+    }
+    if (!deps.interactive()) {
+        deps.print("");
+        deps.print("  Enabling unattended sending needs a terminal to ask in, and this");
+        deps.print("  session has none. Nothing was changed.");
+        deps.print("");
+        deps.print("  Run `vincentt dx enable` yourself, in your own terminal.");
+        deps.print("");
+        return 1;
+    }
+    // What is being granted, INCLUDING the note risk. The note is the part a
+    // creator does not picture: enablement is what lets an agent compose prose they
+    // have not read and put it on the wire.
+    deps.print("");
+    deps.print("  Unattended DX submission");
+    deps.print("");
+    deps.print("  Your agent will be able to send friction reports from this machine without");
+    deps.print("  asking you first. A report includes a note, which is sent exactly as written.");
+    deps.print("  An agent may compose a note you have not read.");
+    deps.print("");
+    deps.print("  This stays on until you run `vincentt dx disable`.");
+    deps.print("");
+    if (!(await deps.confirm("Enable on this machine?"))) {
+        deps.print("");
+        deps.print("  Not enabled.");
+        deps.print("");
+        return 0;
+    }
+    // Written on every enable, so the age reports from the LATEST grant rather than
+    // the first — a re-enable is a fresh decision and dates from when it was made.
+    await deps.save({ at: new Date(deps.now()).toISOString() });
+    deps.print("");
+    deps.print("  Enabled. Reports may now be sent without a prompt.");
+    deps.print("");
+    return 0;
+}
+/**
+ * `vincentt dx disable` — the obvious opposite command.
+ *
+ * Clears BOTH keys. Leaving the timestamp behind would make a later re-enable
+ * report its age from the first grant, which is the kind of thing that ships
+ * wrong and is never noticed. Needs no terminal and no confirmation: turning a
+ * capability OFF is always safe to do, and requiring a TTY here would strand a
+ * creator who wanted to revoke from a script.
+ */
+export async function dxDisableCommand(deps) {
+    await deps.save(undefined);
+    deps.print("");
+    deps.print("  Unattended sending is off. Reports need your confirmation again.");
+    deps.print("");
+    return 0;
+}
 /**
  * `vincentt dx --send`.
  *
@@ -120,7 +224,8 @@ export async function dxSendCommand(deps, options) {
         deps.print(`No friction detected in the last ${options.days} days — nothing to send.`);
         return 0;
     }
-    // --yes REQUIRES a terminal.
+    // SENDING requires either an interactive session or durable enablement — the
+    // gate is on --send, not on --yes.
     //
     // The nudge prints into an agent's transcript, and an agent that reads it has
     // every incentive to act: it just failed four times. Its reflex for an
@@ -129,13 +234,30 @@ export async function dxSendCommand(deps, options) {
     // past in a transcript they may not be reading — which is not the opt-in this
     // feature is built around.
     //
-    // Without --yes there is no such path: the prompt reads EOF under a pipe and
-    // fails closed. So the gate is narrow on purpose — it closes the one way an
-    // autonomous caller could consent on a creator's behalf, and leaves --yes
-    // working for the human who has read the payload.
-    if (options.yes && !deps.interactive()) {
-        deps.print("Sending a DX report is the creator's call, so --yes needs a terminal.");
-        deps.print("Run `vincentt dx --send` yourself, or drop --yes to be asked.");
+    // The gate used to sit on --yes, on the premise that the bare path was safe
+    // because "the prompt reads EOF under a pipe and fails closed". That premise
+    // was false: an empty pipe abandoned the promise rather than refusing, and a
+    // pipe carrying a line answered it — `echo y | vincentt dx --send` transmitted
+    // with no terminal and no human. --yes was never the boundary; --send is, so
+    // the check sits on the act being authorized rather than on a flag that only
+    // modifies how it is confirmed.
+    //
+    // The second arm is the SUPPORTED unattended path: a person, at a terminal,
+    // ran `vincentt dx enable` on this machine. That is a prior deliberate act
+    // rather than a per-send answer, which is what makes it consent at all.
+    const enablement = deps.enablement?.() ?? { enabled: false };
+    const interactive = deps.interactive();
+    if (!interactive && !enablement.enabled) {
+        // This refusal NAMES the enabling command. A refusal is an answer to a
+        // command the caller typed, which makes it SOLICITED output — the
+        // prohibition is on UNBIDDEN output instructing a caller (the nudge names
+        // neither `enable` nor `--send`, and still must not). A refusal naming
+        // nothing satisfies the letter of that rule and leaves a human at exit 1
+        // with no path forward, for no security gain: guessability was never the
+        // threat.
+        deps.print("Sending a report needs your confirmation, and this session has no terminal");
+        deps.print("to ask in. Run `vincentt dx enable` yourself to allow reports from this");
+        deps.print("machine, or run `vincentt dx --send` in your own terminal.");
         return 1;
     }
     const auth = await deps.auth();
@@ -144,10 +266,27 @@ export async function dxSendCommand(deps, options) {
         return 1;
     }
     const report = buildReport(clusters, deps.cliVersion(), options.note);
+    // Above the payload, on the unattended path only: name that this is enabled,
+    // how old the grant is, and that nothing is going to ask.
+    const unattended = !interactive && enablement.enabled;
+    if (unattended) {
+        const line = enablementLine(enablement, deps.now());
+        if (line !== undefined) {
+            deps.print("");
+            deps.print(`${line}. Not asking.`);
+        }
+    }
+    // renderPayload runs on EVERY path, including the unattended one. This is
+    // DISCLOSURE, NOT CONSENT: on the attended path it is what the creator answers
+    // to; unattended it is a forensic artifact that answers "what did we send"
+    // after the fact. Worth its one print, and not to be cited as carrying the
+    // weight the question used to. Only the ASK is ever skipped, never the SHOW.
     for (const l of renderPayload(report))
         deps.print(l);
     deps.print("");
-    if (!options.yes && !(await deps.confirm("Send this report?"))) {
+    // The enabled machine does not ask. --yes still means only "skip the question"
+    // and is inert without one of the two arms above.
+    if (!unattended && !options.yes && !(await deps.confirm("Send this report?"))) {
         deps.print("Not sent.");
         return 0;
     }

package/dist/dx/enablement.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The product-lifetime bound on an explicitly internal-beta capability. Past this
+ * date `enable` refuses AND an existing flag stops being honored, so FORGETTING
+ * THIS TURNS THE FEATURE OFF — the safe direction.
+ *
+ * This is deliberately a constant in shipped code rather than a CI test with a
+ * hard-coded date: such a test fires in an uninvolved engineer's lap at a moment
+ * with no context, and the cheapest green is bumping the constant. Reaching this
+ * date is a decision to make (extend, or remove the feature), not a number to
+ * raise.
+ */
+export declare const DX_UNATTENDED_SUNSET: number;
+export interface Enablement {
+    enabled: boolean;
+    /** The raw ISO8601 grant time. Present only when `enabled` is true. */
+    at?: string;
+}
+/**
+ * Decide enablement from an already-parsed config object. Pure, and STRICT:
+ * identity against `true`, never truthiness.
+ *
+ * Truthiness fails OPEN on `"false"`, `"0"`, `{}`, `[]`, `1`, and `"garbage"` —
+ * every one of those is truthy in JavaScript. The worst is `"false"`, which is
+ * what a person hand-editing this file writes when they are trying to turn the
+ * feature OFF; `{}` is what a refactor grouping the two fields produces. A gate
+ * that reads a creator's "off" as "on" is inverted, not merely loose.
+ */
+export declare function readEnablement(cfg: unknown, now: number): Enablement;
+/**
+ * Read enablement from the real machine config.
+ *
+ * Wrapped in its OWN try/catch, independent of the auth read, because
+ * `readJsonIfExists` rethrows everything that is not ENOENT: a truncated
+ * config.json must DISABLE the relaxation, not throw through it and take an
+ * unrelated verb down with it.
+ */
+export declare function loadEnablement(now: number): Promise<Enablement>;
+/** Whole days elapsed, floored, never negative — a clock skew must not print `(-2 days)`. */
+export declare function ageInDays(at: string, now: number): number;
+/** The calendar day of the grant, in UTC. The time of day is noise at this age scale. */
+export declare function grantedOn(at: string): string;
+/**
+ * The one visibility line, in the single pinned shape every human surface uses:
+ *
+ *   Unattended send: ENABLED since 2026-04-01 (145 days)
+ *
+ * Returns undefined when not enabled. Nothing is printed in that case, on
+ * purpose: a line that prints unconditionally is a line readers learn to skip,
+ * which would cost exactly the attention the enabled line needs.
+ */
+export declare function enablementLine(e: Enablement, now: number): string | undefined;

package/dist/dx/enablement.js

@@ -0,0 +1,97 @@
+/**
+ * Durable authorization for unattended `vincentt dx --send`.
+ *
+ * `--send` transmits only when the session is interactive OR this machine has
+ * been explicitly enabled by a person, at a terminal, via `vincentt dx enable`.
+ * The state is two fields in ~/.vincentt/config.json, set by `enable`, cleared by
+ * `disable` and by `logout`, and it has NO expiry — it stays on until the creator
+ * turns it off.
+ *
+ * Because there is no expiry, VISIBILITY is the entire mitigation, and the AGE is
+ * the load-bearing half of it: `ENABLED` alone reads as configuration, while
+ * `(145 days)` reads as drift and is the number that makes someone ask whether
+ * they still want it. That is why an unparseable timestamp fails CLOSED rather
+ * than printing `since Invalid Date (NaN days)` — a degraded mitigation is worse
+ * than a visible absence.
+ */
+import { loadMachineConfig } from "../shared/config.js";
+/**
+ * The product-lifetime bound on an explicitly internal-beta capability. Past this
+ * date `enable` refuses AND an existing flag stops being honored, so FORGETTING
+ * THIS TURNS THE FEATURE OFF — the safe direction.
+ *
+ * This is deliberately a constant in shipped code rather than a CI test with a
+ * hard-coded date: such a test fires in an uninvolved engineer's lap at a moment
+ * with no context, and the cheapest green is bumping the constant. Reaching this
+ * date is a decision to make (extend, or remove the feature), not a number to
+ * raise.
+ */
+export const DX_UNATTENDED_SUNSET = Date.parse("2027-02-24T00:00:00.000Z");
+const DISABLED = { enabled: false };
+/**
+ * Decide enablement from an already-parsed config object. Pure, and STRICT:
+ * identity against `true`, never truthiness.
+ *
+ * Truthiness fails OPEN on `"false"`, `"0"`, `{}`, `[]`, `1`, and `"garbage"` —
+ * every one of those is truthy in JavaScript. The worst is `"false"`, which is
+ * what a person hand-editing this file writes when they are trying to turn the
+ * feature OFF; `{}` is what a refactor grouping the two fields produces. A gate
+ * that reads a creator's "off" as "on" is inverted, not merely loose.
+ */
+export function readEnablement(cfg, now) {
+    if (typeof cfg !== "object" || cfg === null)
+        return DISABLED;
+    const { dxSendEnabled, dxSendEnabledAt } = cfg;
+    if (dxSendEnabled !== true)
+        return DISABLED;
+    if (typeof dxSendEnabledAt !== "string")
+        return DISABLED;
+    if (!Number.isFinite(Date.parse(dxSendEnabledAt)))
+        return DISABLED;
+    if (now >= DX_UNATTENDED_SUNSET)
+        return DISABLED;
+    return { enabled: true, at: dxSendEnabledAt };
+}
+/**
+ * Read enablement from the real machine config.
+ *
+ * Wrapped in its OWN try/catch, independent of the auth read, because
+ * `readJsonIfExists` rethrows everything that is not ENOENT: a truncated
+ * config.json must DISABLE the relaxation, not throw through it and take an
+ * unrelated verb down with it.
+ */
+export async function loadEnablement(now) {
+    try {
+        return readEnablement(await loadMachineConfig(), now);
+    }
+    catch {
+        return DISABLED;
+    }
+}
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** Whole days elapsed, floored, never negative — a clock skew must not print `(-2 days)`. */
+export function ageInDays(at, now) {
+    const t = Date.parse(at);
+    if (!Number.isFinite(t))
+        return 0;
+    return Math.max(0, Math.floor((now - t) / DAY_MS));
+}
+/** The calendar day of the grant, in UTC. The time of day is noise at this age scale. */
+export function grantedOn(at) {
+    return new Date(Date.parse(at)).toISOString().slice(0, 10);
+}
+/**
+ * The one visibility line, in the single pinned shape every human surface uses:
+ *
+ *   Unattended send: ENABLED since 2026-04-01 (145 days)
+ *
+ * Returns undefined when not enabled. Nothing is printed in that case, on
+ * purpose: a line that prints unconditionally is a line readers learn to skip,
+ * which would cost exactly the attention the enabled line needs.
+ */
+export function enablementLine(e, now) {
+    if (!e.enabled || e.at === undefined)
+        return undefined;
+    const days = ageInDays(e.at, now);
+    return `Unattended send: ENABLED since ${grantedOn(e.at)} (${days} ${days === 1 ? "day" : "days"})`;
+}

package/dist/dx/qa.f7.fixtures.d.ts

@@ -0,0 +1,73 @@
+/**
+ * QA fixtures for the dx-agent-consent delta (f7).
+ *
+ * Declared in the change's qa.md `## Fixtures` section. All three are
+ * machine-config state, which f7 has never had a fixture for — its existing
+ * fixtures (F7_JOURNAL_FRICTION, F7_REPORT_EXPIRED, …) are journal-side or
+ * server-side.
+ *
+ * F7_CONFIG_SIGNED_IN is written by driving the REAL writeMachineConfig(), never
+ * by hand-writing JSON. A hand-written config asserts against a shape the CLI
+ * never produces — the f1 orgs/memberships failure at file scope, where a mock
+ * of state the API could actually produce drifted from the API and stayed green.
+ *
+ * These are QA-owned (qa.* prefix) and deliberately separate from dev's test
+ * files in the same package.
+ */
+import type { JournalEntry } from "./journal.js";
+/** The honest baseline config, as the CLI itself writes it. */
+export declare const F7_CONFIG_SIGNED_IN: {
+    readonly apiUrl: "https://api.test";
+    readonly consoleUrl: "https://console.test";
+    readonly pat: "vct_alice";
+    readonly activeOrg: "alice";
+};
+/**
+ * The instant every fixture is dated against. 145 days after the grant in
+ * F7_CONFIG_ENABLED, and before DX_UNATTENDED_SUNSET.
+ */
+export declare const F7_NOW: number;
+/** 145 days before F7_NOW. The AGE is the point — see qa.md on F7_CONFIG_ENABLED. */
+export declare const F7_ENABLED_AT = "2026-04-01T00:00:00.000Z";
+/**
+ * The single pinned human-facing shape. Every human surface must render this
+ * byte-for-byte; the age is the load-bearing half, so it is pinned as a literal
+ * rather than computed (a computed expectation would follow a broken
+ * implementation wherever it went).
+ */
+export declare const F7_PINNED_ENABLEMENT_LINE = "Unattended send: ENABLED since 2026-04-01 (145 days)";
+/** F7_CONFIG_SIGNED_IN + durable enablement, aged. */
+export declare const F7_CONFIG_ENABLED: {
+    readonly dxSendEnabled: true;
+    readonly dxSendEnabledAt: "2026-04-01T00:00:00.000Z";
+    readonly apiUrl: "https://api.test";
+    readonly consoleUrl: "https://console.test";
+    readonly pat: "vct_alice";
+    readonly activeOrg: "alice";
+};
+/**
+ * Every shape the enablement read must treat as DISABLED.
+ *
+ * Rows B, C, E, F, G are TRUTHY IN JAVASCRIPT — `if (cfg.dxSendEnabled)` passes
+ * every one of them. That is the entire reason this fixture exists, and why the
+ * read is specified as `=== true`. The worst is B ("false"): what a person
+ * hand-editing this file writes when trying to turn the feature OFF.
+ *
+ * `raw` rows (K, L) are written as bytes rather than as an object, because the
+ * property under test is that an UNPARSEABLE config fails closed instead of
+ * throwing through into an unrelated verb.
+ */
+export interface MalformedRow {
+    id: string;
+    why: string;
+    /** A config object to serialize, or undefined when `raw` carries the bytes. */
+    patch?: Record<string, unknown>;
+    /** Literal file bytes, for the rows that are not valid JSON at all. */
+    raw?: string;
+}
+export declare const F7_CONFIG_MALFORMED_ENABLEMENT: MalformedRow[];
+/**
+ * F7_JOURNAL_FRICTION, as the record declares it: three runs of the same verb in
+ * a few minutes, which is a repetition cluster.
+ */
+export declare function f7JournalFriction(now?: number): JournalEntry[];

package/dist/dx/qa.f7.fixtures.js

@@ -0,0 +1,58 @@
+/** The honest baseline config, as the CLI itself writes it. */
+export const F7_CONFIG_SIGNED_IN = {
+    apiUrl: "https://api.test",
+    consoleUrl: "https://console.test",
+    pat: "vct_alice",
+    activeOrg: "alice",
+};
+/**
+ * The instant every fixture is dated against. 145 days after the grant in
+ * F7_CONFIG_ENABLED, and before DX_UNATTENDED_SUNSET.
+ */
+export const F7_NOW = Date.parse("2026-08-24T12:00:00.000Z");
+/** 145 days before F7_NOW. The AGE is the point — see qa.md on F7_CONFIG_ENABLED. */
+export const F7_ENABLED_AT = "2026-04-01T00:00:00.000Z";
+/**
+ * The single pinned human-facing shape. Every human surface must render this
+ * byte-for-byte; the age is the load-bearing half, so it is pinned as a literal
+ * rather than computed (a computed expectation would follow a broken
+ * implementation wherever it went).
+ */
+export const F7_PINNED_ENABLEMENT_LINE = "Unattended send: ENABLED since 2026-04-01 (145 days)";
+/** F7_CONFIG_SIGNED_IN + durable enablement, aged. */
+export const F7_CONFIG_ENABLED = {
+    ...F7_CONFIG_SIGNED_IN,
+    dxSendEnabled: true,
+    dxSendEnabledAt: F7_ENABLED_AT,
+};
+export const F7_CONFIG_MALFORMED_ENABLEMENT = [
+    { id: "A", why: 'truthy STRING "true"', patch: { dxSendEnabled: "true", dxSendEnabledAt: F7_ENABLED_AT } },
+    { id: "B", why: 'truthy in JS, means false to a human', patch: { dxSendEnabled: "false", dxSendEnabledAt: F7_ENABLED_AT } },
+    { id: "C", why: 'truthy in JS ("0")', patch: { dxSendEnabled: "0", dxSendEnabledAt: F7_ENABLED_AT } },
+    { id: "D", why: "truthy, not the boolean (1)", patch: { dxSendEnabled: 1, dxSendEnabledAt: F7_ENABLED_AT } },
+    { id: "E", why: "truthy ({} — what a refactor grouping the fields produces)", patch: { dxSendEnabled: {}, dxSendEnabledAt: F7_ENABLED_AT } },
+    { id: "F", why: "truthy ([])", patch: { dxSendEnabled: [], dxSendEnabledAt: F7_ENABLED_AT } },
+    { id: "G", why: 'truthy ("garbage")', patch: { dxSendEnabled: "garbage", dxSendEnabledAt: F7_ENABLED_AT } },
+    { id: "H", why: "key absent entirely", patch: {} },
+    { id: "I", why: "enabled true, dxSendEnabledAt absent", patch: { dxSendEnabled: true } },
+    { id: "J", why: 'enabled true, dxSendEnabledAt "not-a-date"', patch: { dxSendEnabled: true, dxSendEnabledAt: "not-a-date" } },
+    { id: "K", why: "file truncated mid-JSON", raw: '{"pat":"vct_alice","dxSendEn' },
+    { id: "L", why: "file empty (0 bytes)", raw: "" },
+];
+/**
+ * F7_JOURNAL_FRICTION, as the record declares it: three runs of the same verb in
+ * a few minutes, which is a repetition cluster.
+ */
+export function f7JournalFriction(now = F7_NOW) {
+    const entry = (minutesAgo) => ({
+        ts: new Date(now - minutesAgo * 60_000).toISOString(),
+        v: "0.7.0",
+        verb: "preview",
+        skel: "preview",
+        exit: 0,
+        ms: 800,
+        err: null,
+        wt: "abc123",
+    });
+    return [entry(3), entry(2), entry(1)];
+}

package/dist/dx/skeleton.js

@@ -51,6 +51,7 @@ const KNOWN_FLAGS = new Set([
     "--editor",
     "--errors",
     "--force",
+    "--from",
     "--help",
     "--json",
     "--limit",

package/dist/lib/initCommand.d.ts

@@ -1,8 +1,10 @@
+import type { RegisterDeps } from "./initFrom.js";
+import { type SourceRef } from "./sourceRef.js";
 import type { Ask, Confirm } from "../publish/prompt.js";
 export interface InitDeps {
     print: (line: string) => void;
     cwd: string;
-    scaffold?: (targetDir: string, ref?: string) => Promise<void>;
+    scaffold?: (targetDir: string, opts: ScaffoldCall) => Promise<void>;
     install?: (targetDir: string) => Promise<string>;
     isEmpty?: (targetDir: string) => Promise<boolean>;
     /** Free-text prompt. Absent → not a TTY, so nothing may be asked. */
@@ -11,6 +13,23 @@ export interface InitDeps {
     confirm?: Confirm;
     /** Non-empty check for the resolved target; injected in tests. */
     isNonEmpty?: (targetDir: string) => Promise<boolean>;
+    /**
+     * The registration half of `--from`. Injected whole so the combined path is
+     * drivable without a real API, a real browser, or a real HOME.
+     */
+    register?: (deps: Pick<RegisterDeps, "print" | "targetDir" | "dirLabel" | "ask">, opts: {
+        name?: string;
+        slug?: string;
+    }) => Promise<number>;
+}
+/**
+ * What `InitDeps.scaffold` is called with. An OBJECT rather than a positional
+ * ref: `--from` needs to name a repo too, and a positional-to-object change
+ * compiles silently in a fake that ignores its second argument.
+ */
+export interface ScaffoldCall {
+    repo?: string;
+    ref?: string;
 }
 /** The folder name offered when `init` is run bare and the creator just hits Enter. */
 export declare const DEFAULT_APP_NAME = "my-ar-app";
@@ -27,5 +46,13 @@ export interface InitOptions {
     skipInstall?: boolean;
     /** Template version to scaffold from; defaults to the latest release. */
     template?: string;
+    /**
+     * A gallery source, already parsed. The combined path (f6): clone this repo at
+     * this tag, then register the project. NEVER installs dependencies (S-1).
+     */
+    from?: SourceRef;
+    /** `--name` / `--slug`, accepted on `init` only when `--from` is present. */
+    name?: string;
+    slug?: string;
 }
 export declare function initCommand(deps: InitDeps, opts?: InitOptions): Promise<number>;