@vincentt-xr/cli 0.17.0 → 0.18.0

package/dist/lib/diagnostics.js

@@ -73,9 +73,9 @@ export function renderResult(result, kind, now) {
         .filter(Boolean)
         .join("\n");
     const prefix = header ? `${header}\n` : "";
-    const cursor = `\n\n(latestSeq ${latestSeq} — pass since=${latestSeq} to get only newer ${kind} events)`;
+    const cursor = `\n\n(latestSeq ${latestSeq}; pass since=${latestSeq} to get only newer ${kind} events)`;
     if (lines.length === 0) {
-        return `${prefix}No ${kind} events${latestSeq >= 0 ? " matched" : " yet — is the preview app open on the device?"}.${latestSeq >= 0 ? cursor : ""}`;
+        return `${prefix}No ${kind} events${latestSeq >= 0 ? " matched" : " yet (is the preview app open on the device?)"}.${latestSeq >= 0 ? cursor : ""}`;
     }
     return `${prefix}${lines.join("\n")}${cursor}`;
 }

package/dist/lib/feedback.js

@@ -89,7 +89,7 @@ export async function fetchNext(cwd, opts) {
     const info = await readRelayInfo(cwd);
     if (!info)
         return { kind: "closed", reason: "unreachable" };
-    const base = `http://localhost:${info.relayPort}`;
+    const base = `http://127.0.0.1:${info.relayPort}`;
     const u = new URL(`${info.harnessPath}/feedback/next`, base);
     u.searchParams.set("project", cwd);
     u.searchParams.set("after", String(opts.after));

package/dist/lib/feedbackCopy.js

@@ -86,7 +86,7 @@ export function sessionEnded(handed) {
         "",
         "✗ The preview ended. Nothing more can arrive on it.",
         "",
-        `  Nothing was missed — the ${handed} already handed over stay handed over.`,
+        `  Nothing was missed: the ${handed} already handed over stay handed over.`,
         "",
     ];
 }

package/dist/lib/initFrom.js

@@ -22,7 +22,7 @@ const ORG_SOURCE_LABEL = {
 };
 /** The one sentence every registration-half failure opens with. Byte-identical across arms. */
 function reassure(print, dirLabel) {
-    print(`  Your source is fine — ${dirLabel} is on disk and it's yours.`);
+    print(`  Your source is fine: ${dirLabel} is on disk and it's yours.`);
 }
 /** The resume block: `cd <dir>` (when there is one) then the exact create command. */
 function resume(print, dirLabel, command, needsCd = true) {
@@ -89,7 +89,7 @@ export async function registerAfterScaffold(deps, opts = {}) {
                 // B-F2-9(a): the open route must be named in something the creator's
                 // agent reads. On a non-TTY this output IS that artifact — the TTY
                 // branch's login prompt, which carries the same line, is unreachable here.
-                deps.print("  Or don't — the local dev loop needs no account.");
+                deps.print("  Or don't: the local dev loop needs no account.");
             }
             deps.print("");
             deps.print(closing);
@@ -97,7 +97,7 @@ export async function registerAfterScaffold(deps, opts = {}) {
         }
         deps.print("");
         deps.print("→ Now registering the project so it gets an address.");
-        deps.print("  You're not signed in yet — opening the browser to authorize this device…");
+        deps.print("  You're not signed in yet. Opening the browser to authorize this device…");
         // The open path's load-bearing home, and the only new sentence in this flow.
         // The reader is a human holding working source who is being asked for an
         // account thirty seconds after watching an app appear on their disk — the one
@@ -212,7 +212,7 @@ export async function registerAfterScaffold(deps, opts = {}) {
             // not happening.
             deps.print("");
             deps.print(scaffolded
-                ? "! That address is taken. Your source is fine — pick another."
+                ? "! That address is taken. Your source is fine; pick another."
                 : "! That address is taken. Pick another.");
             if (err.suggestions.length > 0) {
                 deps.print("");

package/dist/lib/lifecycle.d.ts

@@ -26,6 +26,8 @@ export interface CreateOptions {
     runLogin?: () => Promise<void>;
     /** Where the resolved org came from, so a surprising value is diagnosable. */
     orgSource?: () => OrgSource;
+    /** The configured console base, named by the occupied-folder refusal. */
+    consoleUrl?: string;
     /**
      * Stream the transcript as it happens. The CLI passes console.log so a slow
      * create shows progress and the apiUrl advisory lands before the request; MCP

package/dist/lib/lifecycle.js

@@ -55,6 +55,7 @@ export async function projectCreate(projectCwd, opts = {}) {
         currentToken: opts.currentToken,
         runLogin: opts.runLogin,
         orgSource: opts.orgSource,
+        consoleUrl: opts.consoleUrl,
     }, {
         name: opts.name,
         slug: opts.slug,
@@ -116,7 +117,11 @@ export async function projectPublish(projectCwd, opts = {}) {
         binding: async () => {
             const located = await locateProjectBinding(projectCwd);
             return located
-                ? { projectId: located.binding.projectId, slug: located.binding.slug }
+                ? {
+                    projectId: located.binding.projectId,
+                    slug: located.binding.slug,
+                    dir: located.dir,
+                }
                 : undefined;
         },
         token: async () => process.env.VINCENTT_PAT ?? (await loadMachineConfig()).pat,
@@ -306,9 +311,10 @@ async function relayForProject(projectCwd, override) {
     // error instead of the one sentence that tells the creator what to do.
     const info = await readLivePreview(projectCwd);
     if (!info) {
-        throw new Error("No running preview for this project — run `vincentt preview` first.");
+        throw new Error("No running preview for this project. Run `vincentt preview` first.");
     }
-    return httpRelayClient(`http://localhost:${info.relayPort}`);
+    // The relay listens on 127.0.0.1 only; `localhost` may resolve to ::1 first.
+    return httpRelayClient(`http://127.0.0.1:${info.relayPort}`);
 }
 /** Raw diagnostics query against the running relay (used by CLI --json). */
 export async function diagQuery(projectCwd, kind, opts = {}, relay) {

package/dist/lib/listProjects.js

@@ -21,6 +21,7 @@
 // branch is testable with no API, no HOME, and no network.
 import { compactEntries, fileLocationStore, } from "../shared/locationStore.js";
 import { joinLocations, verifyLocation } from "./locations.js";
+import { EXIT } from "./exitCodes.js";
 /** The unknown case, printed rather than omitted. Repeated verbatim in the scaffolded agent contract. */
 export const NO_LOCATION = "no folder known on this machine";
 /** The row's own two spaces, plus four. A CONSTANT — never aligned to a column. */
@@ -37,7 +38,7 @@ export async function listProjectsCommand(deps, opts = {}) {
     const cfg = await deps.config();
     if (!cfg) {
         deps.print("Not signed in. Run `vincentt login`.");
-        return 1;
+        return EXIT.NOT_AUTHENTICATED;
     }
     const org = await deps.org();
     if (!org.ok) {

package/dist/lib/projects.d.ts

@@ -1,8 +1,9 @@
 import { type FolderCase } from "./classifyTarget.js";
-import { type OrgSource } from "./initFrom.js";
+import { registerAfterScaffold, type OrgSource } from "./initFrom.js";
 import type { ScaffoldCall } from "./initCommand.js";
 import { type ScaffoldOutcome } from "../scaffold/index.js";
 import type { Ask } from "../publish/prompt.js";
+import { settleSettings, type JoinFlags } from "./settle.js";
 import { type ResolvedConfig } from "../shared/config.js";
 export interface ProjectCommandDeps {
     /** Print a transcript line. */
@@ -45,6 +46,10 @@ export interface CreateCommandDeps extends ProjectCommandDeps {
     runLogin?: () => Promise<void>;
     /** Where the resolved org came from, so a surprising value is diagnosable (AF-3). */
     orgSource?: () => OrgSource;
+    /** The configured console base, named by the occupied-folder refusal. */
+    consoleUrl?: string;
+    /** Injected for tests. */
+    settle?: typeof settleSettings;
 }
 export interface CreateCommandOptions {
     name?: string;
@@ -67,6 +72,8 @@ export interface CreateCommandOptions {
      * (registering a folder that already holds an app) or when resolution failed.
      */
     templateVersion?: string;
+    /** Run detection and settle vincentt.json after the binding write (case 2). */
+    settleSettings?: boolean;
 }
 /**
  * `vincentt create` — a TWO-HALF verb with one seam.
@@ -89,6 +96,24 @@ export interface CreateCommandOptions {
  * neighbour.
  */
 export declare function createCommand(deps: CreateCommandDeps, opts?: CreateCommandOptions): Promise<number>;
+export interface ClonedRegistrationDeps {
+    /** Resolve the API host + PAT for the cloned directory. */
+    config: (dir: string) => Promise<ResolvedConfig>;
+    /** The org to register in, for the cloned directory. */
+    org: (dir: string) => ReturnType<CreateCommandDeps["org"]>;
+    currentToken: () => Promise<string | undefined>;
+    runLogin: () => Promise<void>;
+    orgSource: () => OrgSource;
+}
+/**
+ * The registration half of `init --from`: `registerAfterScaffold` over
+ * `registerProject`, never over `createCommand`, which would classify and scaffold
+ * a second time inside the half that already cloned.
+ */
+export declare function registerClonedProject(deps: ClonedRegistrationDeps, rd: Pick<Parameters<typeof registerAfterScaffold>[0], "print" | "targetDir" | "dirLabel" | "ask">, opts: {
+    name?: string;
+    slug?: string;
+}): Promise<number>;
 /**
  * The registration half — the binding guard's remainder, the slug derivation, the
  * round trip, and the binding write. Extracted from `createCommand` so
@@ -105,7 +130,17 @@ export declare function registerProject(deps: CreateCommandDeps, opts?: CreateCo
  * "which folder", so linking is entirely client-side, gated only by the server's
  * willingness to return the project at all.
  */
-export declare function linkCommand(deps: ProjectCommandDeps, projectId: string | undefined): Promise<number>;
+export interface LinkOptions {
+    /** `--dev-command`, `--dev-port`, `--build-command`, `--build-output`. */
+    flags?: JoinFlags;
+    /** Machine mode: one JSON object on stdout, never a prompt. */
+    json?: boolean;
+    /** Present only on a TTY. */
+    ask?: Ask;
+    /** Injected for tests. */
+    settle?: typeof settleSettings;
+}
+export declare function linkCommand(deps: ProjectCommandDeps, projectId: string | undefined, opts?: LinkOptions): Promise<number>;
 /**
  * The API's error messages are lowercase and unpunctuated by convention
  * (`that handle is taken`, `this project is not available to you`), while both

package/dist/lib/projects.js

@@ -12,7 +12,10 @@ import { EXIT } from "./exitCodes.js";
 import { registerAfterScaffold } from "./initFrom.js";
 import { slugify } from "./slug.js";
 import { detectPackageManager, installDependencies, scaffoldFromTemplate, } from "../scaffold/index.js";
+import { settleSettings } from "./settle.js";
+import { escapeControl } from "./terminalText.js";
 import { clearProjectBinding, loadProjectBinding, locateProjectBinding, writeProjectBinding, } from "../shared/config.js";
+const DEFAULT_CONSOLE_URL = "https://console.vincentt.studio";
 /**
  * `vincentt create` — a TWO-HALF verb with one seam.
  *
@@ -69,15 +72,30 @@ export async function createCommand(deps, opts = {}) {
         // unforeseen errno. The CLI could not establish that the target is safe to
         // write into; that is one fact with one remedy pair. A per-cause message
         // would advertise which filenames the predicate has opinions about, which is
-        // the allowlist this design refuses to open.
+        // the allowlist this design refuses to open. The one distinction drawn is
+        // whether a package.json exists, which the screen must state truthfully.
+        const hasPackageJson = await fs
+            .lstat(path.join(target, "package.json"))
+            .then((s) => s.isFile())
+            .catch(() => false);
+        const consoleUrl = (deps.consoleUrl ?? DEFAULT_CONSOLE_URL).replace(/\/$/, "");
         deps.print("✗ This folder isn't a Vincentt app, and it isn't empty.");
         deps.print("");
         deps.print("  `vincentt create` scaffolds an empty folder and registers an existing app.");
-        deps.print("  This folder is neither, and adding the template's files here would mix them");
-        deps.print("  into what's already present.");
+        deps.print(hasPackageJson
+            ? "  This folder is neither: nothing in its package.json comes from Vincentt."
+            : "  This folder is neither: it has no package.json.");
         deps.print("");
-        deps.print("  vincentt create <name>   Scaffold and register in a new folder");
-        deps.print("  vincentt init .          Scaffold into THIS folder anyway (asks first)");
+        deps.print("  If this folder holds an app you want on Vincentt:");
+        deps.print(`    1. Create the project in the console:   ${consoleUrl}`);
+        deps.print("    2. Link this folder to it:              vincentt link <project-id>");
+        deps.print("");
+        deps.print("  Or add the harness, then run `vincentt create` again:");
+        deps.print("    npm i @vincentt-xr/harness");
+        deps.print("");
+        deps.print("  To start from the template instead:");
+        deps.print("    vincentt create <name>   Scaffold and register in a new folder");
+        deps.print("    vincentt init .          Scaffold into THIS folder anyway (asks first)");
         deps.print("");
         deps.print("  Nothing was written.");
         return 1;
@@ -164,6 +182,9 @@ export async function createCommand(deps, opts = {}) {
             slug,
             templateVersion,
             rethrowSlugTaken: true,
+            // Case 2 registers an app already on disk, so it settles vincentt.json
+            // the way `link` does. A fresh scaffold IS the template.
+            settleSettings: !scaffolded,
         }),
     }, 
     // Case 2 keeps the shipped basename default: a creator made that folder and
@@ -316,6 +337,35 @@ async function scaffoldInto(deps, target, dirLabel, opts) {
     deps.print(`✓ Created ${dirLabel}`);
     return { ok: true, installed, pm, templateVersion: scaffoldResult?.templateVersion };
 }
+/**
+ * The registration half of `init --from`: `registerAfterScaffold` over
+ * `registerProject`, never over `createCommand`, which would classify and scaffold
+ * a second time inside the half that already cloned.
+ */
+export function registerClonedProject(deps, rd, opts) {
+    let cachedOrg;
+    const org = async () => (cachedOrg ??= await deps.org(rd.targetDir));
+    return registerAfterScaffold({
+        ...rd,
+        currentToken: deps.currentToken,
+        runLogin: deps.runLogin,
+        resolveOrg: async () => {
+            const resolved = await org();
+            if (!resolved.ok)
+                return resolved;
+            return { ok: true, name: resolved.org.name, source: deps.orgSource() };
+        },
+        create: async ({ name, slug }) => registerProject({
+            print: rd.print,
+            cwd: rd.targetDir,
+            config: () => deps.config(rd.targetDir),
+            org,
+        }, 
+        // Without this the taken-address refusal prints here and returns, and
+        // the bounded re-ask in registerAfterScaffold never sees the 409.
+        { name, slug, rethrowSlugTaken: true }),
+    }, opts);
+}
 /**
  * The registration half — the binding guard's remainder, the slug derivation, the
  * round trip, and the binding write. Extracted from `createCommand` so
@@ -369,6 +419,14 @@ export async function registerProject(deps, opts = {}) {
     deps.print(`✓ Created ${created.name} in ${org.org.name}`);
     deps.print(`  Address reserved:  ${created.liveUrl}`);
     deps.print(`  Linked this folder: .vincentt/project.json   (added to .gitignore)`);
+    if (opts.settleSettings) {
+        // Between the binding line and today's closing lines, so the last lines are
+        // still the ones a creator acts on. A template prints nothing here.
+        await (deps.settle ?? settleSettings)(target, await loadProjectBinding(target), {}, {
+            print: deps.print,
+            ask: deps.ask,
+        });
+    }
     deps.print("");
     deps.print("  Nothing is served at that address until you publish.");
     deps.print("  Run `vincentt preview` to try it on your phone.");
@@ -401,15 +459,7 @@ function printSlugTaken(print, suggestions, name) {
     }
     print(`  Run \`vincentt create --name "${name}" --slug <address>\` with another address.`);
 }
-// ---- link -------------------------------------------------------------------
-/**
- * `vincentt link <project-id>` — one verb for four situations (console-first
- * birth, a fresh clone, a folder that lost its binding, a re-link after
- * `login --force`). It is a READ plus a local write: the server has no notion of
- * "which folder", so linking is entirely client-side, gated only by the server's
- * willingness to return the project at all.
- */
-export async function linkCommand(deps, projectId) {
+export async function linkCommand(deps, projectId, opts = {}) {
     if (!projectId) {
         deps.print("✗ Which project? `vincentt link` needs a project id.");
         deps.print("");
@@ -429,16 +479,31 @@ export async function linkCommand(deps, projectId) {
         }
         throw err;
     }
+    const text = opts.json ? () => undefined : deps.print;
     if (existing && existing.projectId !== project.id) {
-        deps.print(`!  This folder is already linked to ${existing.slug}.`);
-        deps.print(`   Re-linking it to ${project.name}.`);
-        deps.print("");
+        text(`!  This folder is already linked to ${existing.slug}.`);
+        text(`   Re-linking it to ${project.name}.`);
+        text("");
     }
     await writeProjectBinding(deps.cwd, { projectId: project.id, slug: project.slug });
-    deps.print(`✓ Linked this folder to ${project.name}`);
+    text(`✓ Linked this folder to ${project.name}`);
     if (project.liveUrl)
-        deps.print(`  Address: ${project.liveUrl}`);
-    deps.print("  Wrote .vincentt/project.json   (added to .gitignore)");
+        text(`  Address: ${project.liveUrl}`);
+    text("  Wrote .vincentt/project.json   (added to .gitignore)");
+    // Settled only after a successful binding write: a refused link writes no file.
+    const joined = await (opts.settle ?? settleSettings)(deps.cwd, await loadProjectBinding(deps.cwd), opts.flags ?? {}, { print: deps.print, ask: opts.json ? undefined : opts.ask, json: opts.json });
+    if (opts.json) {
+        // JSON escapes C0 controls itself; the C1 range still needs the same escape.
+        deps.print(escapeControl(JSON.stringify({
+            project: { id: project.id, slug: project.slug, name: project.name, liveUrl: project.liveUrl },
+            ...joined.json,
+        })));
+        return 0;
+    }
+    if (joined.reported) {
+        deps.print("");
+        deps.print("  Run `vincentt preview` to try it on your phone.");
+    }
     return 0;
 }
 /**
@@ -487,7 +552,7 @@ export async function unlinkCommand(deps) {
     }
     deps.print("✓ Unlinked. Removed .vincentt/project.json");
     deps.print("");
-    deps.print("  The project itself is untouched — this only disconnects this folder.");
+    deps.print("  The project itself is untouched; this only disconnects this folder.");
     deps.print("  Run `vincentt link <project-id>` to link it again.");
     return 0;
 }

package/dist/lib/settings.d.ts

@@ -0,0 +1,113 @@
+export declare const SETTINGS_FILE = "vincentt.json";
+export declare const SETTINGS_SCHEMA_URL = "https://vincentt.studio/schema/vincentt.json";
+export declare const SETTINGS_MAX_BYTES = 4096;
+export type SettingsField = "dev.command" | "dev.port" | "build.command" | "build.output";
+export declare const SETTINGS_FIELDS: readonly SettingsField[];
+export interface VincenttJson {
+    $schema?: string;
+    dev?: {
+        command?: string;
+        port?: number;
+    };
+    build?: {
+        command?: string;
+        output?: string;
+    };
+}
+export type Source = "flag" | "vincentt.json" | "default";
+export interface Resolved<T> {
+    value: T;
+    source: Source;
+    /** The flag that supplied it, when source is "flag". */
+    flag?: string;
+}
+export interface ResolvedSettings {
+    devCommand: Resolved<string>;
+    devPort: Resolved<number>;
+    buildCommand?: Resolved<string>;
+    buildOutput: Resolved<string>;
+}
+export interface SettingsDefaults {
+    devCommand: string;
+    devPort: number;
+    buildOutput: string;
+}
+export declare const TEMPLATE_DEFAULTS: SettingsDefaults;
+export type SettingsProblem = {
+    kind: "missing";
+    field: SettingsField;
+    flag: string;
+} | {
+    kind: "unknown_key";
+    key: string;
+} | {
+    kind: "invalid_json";
+    line?: number;
+    column?: number;
+} | {
+    kind: "bad_value";
+    field: SettingsField | "$schema";
+    value: unknown;
+    message: string;
+} | {
+    kind: "not_object";
+} | {
+    kind: "too_large";
+} | {
+    kind: "not_file";
+};
+export declare class SettingsError extends Error {
+    readonly problem: SettingsProblem;
+    constructor(problem: SettingsProblem);
+}
+/** One sentence naming what is wrong, for advisories that are not the full refusal. */
+export declare function describeProblem(p: SettingsProblem): string;
+/**
+ * The schema rule for one field's value, as the message a prompt or a refusal
+ * prints. `undefined` means the value is acceptable. Shared by the file parser,
+ * the joining prompts and the flag values, so there is one rule.
+ */
+export declare function validateField(field: SettingsField, value: unknown): string | undefined;
+/** Parse a typed or flagged value into the field's type, then validate it. */
+export declare function coerceField(field: SettingsField, raw: string): {
+    ok: true;
+    value: string | number;
+} | {
+    ok: false;
+    message: string;
+};
+/** Parse the file's text. Throws SettingsError; never returns a partial object. */
+export declare function parseSettings(text: string): VincenttJson;
+export declare function fieldOf(file: VincenttJson, field: SettingsField): string | number | undefined;
+export interface SettingsIo {
+    readFile: (p: string) => Promise<string>;
+}
+/**
+ * Read `vincentt.json` without trusting what it is. Opened non-blocking so a
+ * FIFO cannot park the open, then checked on the OPEN descriptor to be a
+ * regular file of at most 4 KB, and read no further than one byte past the cap.
+ * A symlink to /dev/zero is a character device and is refused before any read.
+ * Throws ENOENT (absent) or SettingsError (present but unusable).
+ */
+export declare function readSettingsText(abs: string): Promise<string>;
+/**
+ * The file at `root`, or undefined when there is none. A present file that
+ * cannot be used throws: an unreadable file is never treated as absent, or a
+ * typo would silently restore the template defaults.
+ */
+export declare function readSettings(root: string, io?: SettingsIo): Promise<VincenttJson | undefined>;
+export interface SettingsFlags {
+    devCommand?: string;
+    devPort?: number;
+    buildOutput?: string;
+}
+type Need = "dev" | "build";
+/**
+ * Resolve the fields a verb needs. `need` scopes the refusal: preview never
+ * refuses over a missing build.output, and publish never over a missing dev
+ * port. build.command is never refused anywhere, because nothing runs it.
+ */
+export declare function resolveSettings(flags: SettingsFlags, file: VincenttJson | undefined, defaults?: SettingsDefaults, need?: readonly Need[]): ResolvedSettings;
+/** The file as joining writes it: 2-space indentation and a trailing newline. */
+export declare function serializeSettings(values: Partial<Record<SettingsField, string | number>>): string;
+export {};