@vincentt-xr/cli 0.17.0 → 0.18.1

package/MIGRATION.md

@@ -0,0 +1,31 @@
+# Migration notes
+
+Per version, newest first. Read by the platform's own version surface and served to
+creators' agents. Accurate or absent, never speculative (B-F5-2).
+
+## 0.18.1
+
+required: false
+No action required. Behaviour that changed:
+- `publish` re-opens the upload when an upload link expires (at most twice) instead of failing. Network errors and S3 5xx are retried with backoff. A refused upload reports "changed while uploading" only when S3 says the bytes do not match; other refusals name the failed file.
+- A publish that fails on the network leaves its upload open, so running `vincentt publish` again sends only the files that have not landed yet (on an API that supports it). Files stream from disk instead of being read into memory.
+
+## 0.18.0
+
+required: false
+No action required for a project made from the Vincentt template. Behaviour that changed:
+- An app not made from the template can be linked; `vincentt link` then writes a committed `vincentt.json` describing how it runs. `publish --dist <folder>` resolves against the linked project folder, not the current directory, and refuses a folder that is the project root, lies outside it, or holds a hidden file other than `.well-known` / `.nojekyll`.
+- The preview proxy and the local relay listen on 127.0.0.1 only. The preview proxy gzips text responses (JavaScript, CSS, HTML, JSON, SVG) for clients that accept gzip.
+- Every verb that needs an account now exits 4 (not signed in) with the `vincentt login` remedy, whether no token is stored or the API refuses the stored one; with no stored token `publish`, `preview`, `link`, `projects`, `whoami` and `dx` used to exit 1. A running preview whose heartbeat is refused ends and exits 4. Without a terminal, `link` and `projects` refuse at once instead of waiting on a browser sign-in. `create` in a folder that already holds an app still exits 1.
+- `publish` on a project Vincentt has taken offline over its traffic allowance exits 1 before prompting and uploads nothing; it used to upload the whole build and be refused at the end. `publish` prints `Live at` only for an address that is serving. A published address that serves nothing shows a not-serving checklist, and an unrecognised state defaults its prompt to no.
+- A preview ending names its real cause (for example stopped from another terminal, or abandoned) instead of always reporting a dropped connection. `preview --stop` exits 1 when there was no preview to stop. `domain attach` at the custom-domain limit states the real allowance; a plan with none is told custom domains are part of the paid plans.
+- With no API configured, every verb uses https://api.vincentt.studio; `publish` and `preview` used to fall back to http://localhost:5051. Every API call and upload now gives up after a deadline instead of waiting forever.
+- A publish whose final switch-over answer is lost retries up to three times, then says the version may or may not be live instead of crashing. Ctrl-D at a name or address prompt cancels instead of hanging. Output lines no longer use em-dashes (the preview ending lines are unchanged for now), so a script matching the old wording exactly needs updating.
+- `publish` prints `Live at` only once the public address serves the new `index.html`, printing a `Propagating` line while it waits (up to 90 s). If the wait runs out it still exits 0 and says the version is published but not yet visible. `publish --json` (with `--yes`) prints one JSON object on stdout whose `state` is `live`, `committed_not_visible` or `failed`; the human output moves to stderr.
+- `login` with a stored token checks it before reporting signed in. A refused token runs the sign-in again; when the account cannot be checked the token is kept and `login` exits 1 (it used to exit 0 and print "your account"). `init --from` re-asks for an address when the chosen one is taken, up to three attempts, instead of exiting at the first refusal.
+- `vincentt dx` and `dx --send` look at the last 24 hours of runs by default, not the last 7 days. `--since <duration>` (for example `30m`, `2h`, `7d`) sets the window and the report names it; an unreadable duration exits 1. `--days <n>` still works. `feedback --wait` no longer skips an annotation when several arrive at once; every one is handed over in order.
+
+## 0.17.0
+
+required: false
+No action required.

package/README.md

@@ -65,7 +65,10 @@ Project
                        if the folder is empty
                        [--name <s>] [--slug <s>] [--org <s>] [--preview]
                        [--force] [--no-install]
-  link <project-id>  Link this directory to an existing project
+  link <project-id>  Link this directory to an existing project; for an app not
+                       made from the template, also writes vincentt.json
+                       [--json] [--dev-command <cmd>] [--dev-port <n>]
+                       [--build-command <cmd>] [--build-output <folder>]
   unlink             Detach this directory from its project
   projects           List the workspace's projects, their ids, and where each
                        one lives on this machine
@@ -73,8 +76,11 @@ Project
 
 Dev loop
   publish            Upload the built dist; go live at <slug>.vincentt.app
+                       [--dist <folder>] (relative to the project folder)
+                       [--yes] [--json]
   preview            Serve + tunnel the app for on-device preview
                        (prints a desktop QR page to scan) [--stop]
+                       [--port <n>] [--dev-command <cmd>]
 
 Diagnostics (need a running preview)
   logs [--errors]    Console logs from the device   [--json]
@@ -115,6 +121,14 @@ later verbs run without prompting. `init` never reaches that gate at all.
   there. A count that cannot be read prints no line rather than a guess.
 - `npx vincentt publish` — build (`pnpm build`), then upload the built `dist/` and
   return the live `<slug>.vincentt.app` URL. Nothing builds server-side.
+  The CDN takes a few seconds to switch to a new version, so after the upload
+  `publish` prints a `→ Propagating` line and checks the address until it
+  serves the `index.html` just uploaded. Only then does it print `✓ Live at`. It
+  waits up to 90 seconds; past that it exits 0 and says the version is published
+  but not yet visible, because the publish did happen and publishing again would
+  not help. `--json` (with `--yes`) puts the human output on stderr and prints one
+  object on stdout whose `state` is `live` or `committed_not_visible` (with
+  `version`, `liveUrl` and `waitedMs`), or `failed` (with `exitCode`).
 
 In a directory that is not linked to anything, `npx vincentt projects` lists the
 workspace's projects with their ids, which is what `vincentt link <project-id>`
@@ -140,3 +154,82 @@ deleting `~/.vincentt/locations.ndjson` costs nothing but the shortcut.
 
 `vincentt` is a project devDependency in the scaffold, so invoke it as
 `npx vincentt <verb>` and it resolves to the local copy — no global install.
+
+## An app that isn't built on the Vincentt template
+
+Any app with a local dev server and a static build output can join: create the
+project in the console, then run `vincentt link <project-id>` in the app's folder.
+(`vincentt create` also registers a non-empty folder whose `package.json` already
+lists a `@vincentt-xr/*` package, and does the same.)
+
+Besides the gitignored binding, `link` reads how the app runs from
+`package.json`, the lockfile's name and at most one bundler config. **It runs
+nothing**: no script, no config evaluation, no install. It writes what it found to
+`vincentt.json` at the project root:
+
+```json
+{
+  "$schema": "https://vincentt.studio/schema/vincentt.json",
+  "dev": { "command": "npm run serve", "port": 8080 },
+  "build": { "command": "npm run build", "output": "dist" }
+}
+```
+
+- `dev.command` is what `vincentt preview` starts, and `dev.port` is the port it
+  forwards to. `build.output` is the folder `vincentt publish` uploads.
+  `build.command` is recorded and printed, never run: publish uploads a folder
+  that is already built.
+- **Commit it**, so every clone previews and publishes the same way. It holds no
+  project id, account, URL or credential.
+- **A present file is the whole truth.** A field missing from it is refused by
+  name (`vincentt.json has no dev.port.`); defaults apply only when there is no
+  file at all. A flag (`--port`, `--dev-command`, `--dist`) overrides one field
+  for one run.
+- `vincentt.json` runs a command on every collaborator's machine at `preview`,
+  like a `package.json` script. Review changes to it in pull requests. The
+  command runs without the CLI's access token in its environment.
+- When detection cannot find a field, `link` still succeeds and prints the
+  `vincentt.json` edit and the one-run flag. In a terminal it asks for each value
+  first. `vincentt link <id> --json` prints the result for a program to read, and
+  never asks.
+- `--dist` and `build.output` are relative to the project folder (the one that
+  holds `.vincentt/project.json`), not the directory the command runs in.
+- A project made from the Vincentt template is recognised and gets no
+  `vincentt.json`: its defaults are `npm run dev`, port 5173 and `dist`.
+
+### Diagnostics for an app that isn't built on the Vincentt template
+
+`vincentt preview` works without this. Adding it makes `vincentt logs`, `network` and
+`trace` report what happens on the phone, and lets the console reach the preview.
+
+1. Install the harness:
+
+   ```sh
+   npm i @vincentt-xr/harness
+   ```
+
+2. Add this line at the top of your entry file, before anything else runs:
+
+   ```js
+   import "@vincentt-xr/harness/auto";
+   ```
+
+That is the whole change. It needs no React and no build setting.
+
+The line switches itself on only on a Vincentt preview address (`*.vincentt.dev`). Everywhere
+else, including your published address, GitHub Pages, Vercel, Netlify and `localhost`, it does
+nothing at all: no network request, no page change, no console output.
+
+Do not add it to a project made from the Vincentt template; the template already includes the
+harness.
+
+### What publish checks first
+
+Before any upload, `vincentt publish` refuses an output that is the project
+folder itself or lies outside it, holds any name starting with `.` (other than
+`.well-known/` and `.nojekyll` at its root), holds a symlink that resolves outside
+the project or onto a hidden path, or holds Git LFS pointer files instead of the
+assets (`git lfs pull`, then rebuild). A `<script src>`, stylesheet, image or media
+reference that starts with `/` and is not in the output is reported as a warning:
+Vincentt serves the app at the root of its address, so a build made for a subpath
+(a GitHub Pages project site) will not find those files.

package/dist/cli/index.js

@@ -18,10 +18,11 @@ import { runPkceLogin } from "../login/pkceLogin.js";
 import { httpAuthBackend } from "../login/authBackend.js";
 import { loginCommand } from "../login/loginCommand.js";
 import { ensureLoggedIn } from "../login/ensure.js";
-import { clearMachineToken, loadMachineConfig, locateProjectBinding, resolveConfig, writeDxEnablement, MACHINE_CONFIG_PATH, } from "../shared/config.js";
+import { clearMachineToken, loadMachineConfig, locateProjectBinding, machineApiUrl, resolveConfig, writeDxEnablement, MACHINE_CONFIG_PATH, } from "../shared/config.js";
 import { fileLocationStore } from "../shared/locationStore.js";
 import { getMe, listProjects, ProjectUnreachableError } from "../lib/backend.js";
 import { EXIT } from "../lib/exitCodes.js";
+import { AuthExpiredError, authExpiredLines, isAuthRefused, NOT_SIGNED_IN_LINES, NotSignedInError, } from "../shared/authError.js";
 import { listProjectsCommand } from "../lib/listProjects.js";
 import { initCommand } from "../lib/initCommand.js";
 import { linkCommand, printUnreachable, unlinkCommand } from "../lib/projects.js";
@@ -36,14 +37,18 @@ import { USAGE_TEXT } from "./usage-text.js";
 import { PreviewUi } from "../preview/command.js";
 import { httpRelayClient } from "../lib/diagnostics.js";
 import { readLivePreview, relayInfoDir } from "../lib/relayInfo.js";
-import { attachedToRunning, mintRateLimited, notSignedIn, previewConflict, startBlock, } from "../preview/copy.js";
+import { attachedToRunning, mintRateLimited, noDiagnosticsStatic, notSignedIn, previewConflict, settingsBanner, startBlock, } from "../preview/copy.js";
+import { isPortListening } from "../preview/net.js";
+import { readSettings, resolveSettings, SettingsError, TEMPLATE_DEFAULTS, validateField, } from "../lib/settings.js";
+import { settingsRefusal, sourceWords } from "../lib/settingsCopy.js";
+import { listsHarness } from "../lib/template.js";
 import { renderTerminalQr, shouldRenderQr } from "../preview/qr.js";
 import { PreviewConflictError, PreviewLimitError, PreviewRateLimitedError, } from "../preview/api.js";
 import { previewLimitRefused, resolveCountLimit, } from "../shared/countLimit.js";
 import { fetchNext, readCursor, writeCursor } from "../lib/feedback.js";
 import * as feedbackCopy from "../lib/feedbackCopy.js";
 import { record as recordInvocation } from "../dx/journal.js";
-import { dxDisableCommand, dxEnableCommand, dxSendCommand, parseDxOptions, runDx, } from "../dx/command.js";
+import { dxDisableCommand, dxEnableCommand, dxSendCommand, parseDxOptions, runDx, sinceUsageLines, } from "../dx/command.js";
 import { httpConsentBackend, runConsentInBrowser } from "../dx/consent.js";
 import { DX_UNATTENDED_SUNSET, loadEnablement } from "../dx/enablement.js";
 import { journalEnabled, journalPath, readJournal } from "../dx/journal.js";
@@ -53,14 +58,13 @@ import { FETCH_TIMEOUT_MS, isFresh, updateNotice } from "../dx/updateCheck.js";
 import { fetchLatest, loadCache, saveCache } from "../dx/updateCheckIo.js";
 import { verbOf } from "../dx/skeleton.js";
 import { outdatedCommand } from "../platform/command.js";
-import { behindFooterLines, needsRefresh, refreshReleaseCache } from "../platform/footer.js";
+import { behindFooterLines, needsRefresh, refreshReleaseCache, } from "../platform/footer.js";
 import { loadReleaseCache } from "../platform/releaseCache.js";
 import { resolveBuiltWith } from "../platform/resolve.js";
 import { createDirCollision, createSourceFlagRefusal, fromFlagConflict, isHelpInvocation, isVersionInvocation, positionalArgs, refusedFlag, } from "./args.js";
 import { parseSourceRef } from "../lib/sourceRef.js";
 import { printCreateSourceFlagRefusal, printFlagConflict, printSourceRefFailure, } from "../lib/sourceRefCopy.js";
-import { registerAfterScaffold } from "../lib/initFrom.js";
-import { registerProject } from "../lib/projects.js";
+import { registerClonedProject } from "../lib/projects.js";
 import { sanitizeAppName } from "../lib/initCommand.js";
 import { resolveOrgForCommand } from "../lib/lifecycle.js";
 // The console origin serves /cli-auth (the browser target for `vincentt login`). VINCENTT_
@@ -68,7 +72,6 @@ import { resolveOrgForCommand } from "../lib/lifecycle.js";
 // This is the prod console; vincentt.app is the published-PROJECT apex, not the console, so a
 // first-run `vincentt login` (no machine config yet) must default here or it opens a dead page.
 const DEFAULT_CONSOLE_URL = "https://console.vincentt.studio";
-const DEFAULT_API_URL = "https://api.vincentt.studio";
 // ---- arg helpers ------------------------------------------------------------
 const argv = process.argv.slice(2);
 function flag(name) {
@@ -108,8 +111,12 @@ async function resolveAuthUrls() {
         process.env.VINCENTT_EDITOR_URL ??
         machine.consoleUrl ??
         DEFAULT_CONSOLE_URL;
-    const apiUrl = flag("--api") ?? process.env.VINCENTT_API_URL ?? machine.apiUrl ?? DEFAULT_API_URL;
-    return { consoleUrl, apiUrl };
+    return { consoleUrl, apiUrl: machineApiUrl(machine, flag("--api")) };
+}
+/** The machine's own host and token, never the folder's binding. Undefined when signed out. */
+function machineCredentials(machine) {
+    const pat = process.env.VINCENTT_PAT ?? machine.pat;
+    return pat ? { apiUrl: machineApiUrl(machine), pat } : undefined;
 }
 /** The PKCE loopback + code-exchange login (f1). The raw PAT never rides a redirect query. */
 async function runLoginFlow() {
@@ -129,13 +136,8 @@ async function login() {
         whoAmI: async () => {
             const pat = await currentToken();
             if (!pat)
-                return undefined;
-            try {
-                return await httpAuthBackend(apiUrl).me(pat);
-            }
-            catch {
-                return undefined;
-            }
+                throw new NotSignedInError();
+            return httpAuthBackend(apiUrl).me(pat);
         },
         runLogin: runLoginFlow,
         clearToken: async () => {
@@ -150,13 +152,20 @@ async function login() {
 async function currentToken() {
     return process.env.VINCENTT_PAT ?? (await loadMachineConfig()).pat;
 }
-/** Guard an auth-requiring verb: log in inline on first run instead of erroring. */
+/**
+ * Guard an auth-requiring verb: log in inline at a terminal, refuse at once
+ * without one. False means the caller must stop; the exit code is already set.
+ */
 async function requireLogin() {
-    await ensureLoggedIn({
+    const ok = await ensureLoggedIn({
         currentToken,
         runLogin: login,
         notify: (m) => console.error(m),
+        interactive: Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY),
     });
+    if (!ok)
+        process.exitCode = EXIT.NOT_AUTHENTICATED;
+    return ok;
 }
 async function logout() {
     const { path: p, hadToken } = await clearMachineToken();
@@ -171,14 +180,7 @@ async function whoami() {
     const machine = await loadMachineConfig();
     process.exitCode = await whoamiCommand({
         print: (l) => console.log(l),
-        config: async () => {
-            const apiUrl = process.env.VINCENTT_API_URL ?? machine.apiUrl ?? DEFAULT_API_URL;
-            const pat = process.env.VINCENTT_PAT ?? machine.pat;
-            if (!pat)
-                return undefined;
-            const cfg = { apiUrl: apiUrl.replace(/\/$/, ""), pat };
-            return cfg;
-        },
+        config: async () => machineCredentials(machine),
         getMe,
         org: {
             flag: flag("--org"),
@@ -220,35 +222,17 @@ async function init() {
         ask: interactive ? stdinAsk() : undefined,
         confirm: interactive ? stdinConfirm() : undefined,
         register: from
-            ? (rd, o) => registerAfterScaffold({
-                ...rd,
+            ? (rd, o) => registerClonedProject({
+                config: (dir) => resolveConfig(dir, { warn: print }),
+                org: async (dir) => resolveOrgForCommand(await resolveConfig(dir, { warn: print }), {
+                    flag: flag("--org"),
+                }),
                 currentToken,
                 runLogin: async () => {
                     await login();
                 },
-                resolveOrg: async () => {
-                    const cfg = await resolveConfig(rd.targetDir, { warn: print });
-                    const resolved = await resolveOrgForCommand(cfg, {
-                        flag: flag("--org"),
-                    });
-                    if (!resolved.ok)
-                        return resolved;
-                    return {
-                        ok: true,
-                        name: resolved.org.name,
-                        source: orgSource(),
-                    };
-                },
-                // registerProject, NOT createCommand: createCommand is now the
-                // whole two-half verb, so calling it here would classify and
-                // scaffold a second time inside the half that already cloned.
-                create: async ({ name, slug }) => registerProject({
-                    print,
-                    cwd: rd.targetDir,
-                    config: () => resolveConfig(rd.targetDir, { warn: print }),
-                    org: async () => resolveOrgForCommand(await resolveConfig(rd.targetDir, { warn: print }), { flag: flag("--org") }),
-                }, { name, slug }),
-            }, o)
+                orgSource,
+            }, rd, o)
             : undefined,
     }, {
         dir,
@@ -344,6 +328,7 @@ async function create() {
             await login();
         },
         orgSource,
+        consoleUrl: (await resolveAuthUrls()).consoleUrl,
         onLine: (l) => console.log(l),
     });
     if (result.exitCode !== 0) {
@@ -357,16 +342,30 @@ async function create() {
     }
 }
 async function link() {
-    await requireLogin();
+    if (!(await requireLogin()))
+        return;
     const cwd = projectDir();
+    const json = has("--json");
+    const interactive = Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY);
+    const value = (name) => flag(name) ?? valueOfEqualsFlag(argv, name);
     process.exitCode = await linkCommand({
         print: (l) => console.log(l),
         cwd,
         config: () => resolveConfig(cwd, {
             allowCustomApi: has("--allow-custom-api"),
-            warn: (l) => console.log(l),
+            // Under --json stdout carries the one JSON object only.
+            warn: (l) => (json ? console.error(l) : console.log(l)),
         }),
-    }, positional(1));
+    }, positional(1), {
+        json,
+        ask: interactive && !json ? stdinAsk() : undefined,
+        flags: {
+            devCommand: value("--dev-command"),
+            devPort: value("--dev-port"),
+            buildCommand: value("--build-command"),
+            buildOutput: value("--build-output"),
+        },
+    });
 }
 async function unlink() {
     const cwd = projectDir();
@@ -386,13 +385,10 @@ async function unlink() {
  * BECAUSE they are in an unbound folder depend on that folder having a binding.
  */
 async function projects() {
-    await requireLogin();
+    if (!(await requireLogin()))
+        return;
     const machine = await loadMachineConfig();
-    const config = async () => {
-        const apiUrl = process.env.VINCENTT_API_URL ?? machine.apiUrl ?? DEFAULT_API_URL;
-        const pat = process.env.VINCENTT_PAT ?? machine.pat;
-        return pat ? { apiUrl: apiUrl.replace(/\/$/, ""), pat } : undefined;
-    };
+    const config = async () => machineCredentials(machine);
     process.exitCode = await listProjectsCommand({
         print: (l) => console.log(l),
         config,
@@ -420,7 +416,7 @@ async function outdated() {
         print: (l) => console.log(l),
         cwd,
         now: () => Date.now(),
-        apiUrl: async () => process.env.VINCENTT_API_URL ?? (await loadMachineConfig()).apiUrl ?? DEFAULT_API_URL,
+        apiUrl: async () => machineApiUrl(await loadMachineConfig()),
         inProject: async () => (await locateProjectBinding(cwd)) !== undefined,
         projectLine: async () => {
             const name = await projectDisplayName(cwd);
@@ -447,29 +443,38 @@ async function publish() {
         return;
     }
     const cwd = projectDir();
+    // Under --json stdout carries the one JSON object only; everything else goes to stderr.
+    const json = has("--json");
+    const say = (l) => (json ? console.error(l) : console.log(l));
     process.exitCode = await publishCommand({
-        print: (l) => console.log(l),
-        write: (s) => process.stdout.write(s),
+        print: say,
+        write: (s) => (json ? process.stderr : process.stdout).write(s),
+        emit: (l) => console.log(l),
         confirm: stdinConfirm(),
         cwd,
         config: () => resolveConfig(cwd, {
             allowCustomApi: has("--allow-custom-api"),
-            warn: (l) => console.log(l),
+            warn: say,
         }),
         binding: async () => {
             const located = await locateProjectBinding(cwd);
             return located
-                ? { projectId: located.binding.projectId, slug: located.binding.slug }
+                ? {
+                    projectId: located.binding.projectId,
+                    slug: located.binding.slug,
+                    dir: located.dir,
+                }
                 : undefined;
         },
         token: currentToken,
-        isTTY: Boolean(process.stdout.isTTY) && Boolean(process.stdin.isTTY),
+        // A prompt would land in the JSON document, so --json needs --yes.
+        isTTY: !json && Boolean(process.stdout.isTTY) && Boolean(process.stdin.isTTY),
         now: () => Date.now(),
         sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
         orgName: activeOrgName,
         orgSlug: async () => (await activeOrgName()) || undefined,
         consoleUrl: flag("--console") ?? process.env.VINCENTT_CONSOLE_URL,
-    }, { distDir: flag("--dist"), note: flag("--note"), yes: has("--yes") });
+    }, { distDir: flag("--dist"), note: flag("--note"), yes: has("--yes"), json });
 }
 /** Flow L30 — the six verbs that are console actions, answered rather than rejected. */
 async function consoleOnly(verb) {
@@ -492,16 +497,61 @@ async function consoleOnly(verb) {
 async function preview() {
     const cwd = projectDir();
     if (has("--stop")) {
-        const { message } = await previewStopSignal(cwd);
+        const { stopped, message } = await previewStopSignal(cwd);
         console.log(message);
+        // Non-zero when nothing was stopped, so a script can tell "stopped" from "there was nothing".
+        process.exitCode = stopped ? EXIT.OK : EXIT.FAILED;
         return;
     }
+    // Settings resolve first and locally: a refusal touches nothing, and the
+    // banner is the disclosure of the dev command before anything runs.
+    const settingsRoot = (await locateProjectBinding(cwd))?.dir ?? cwd;
+    const portFlag = flag("--port") ?? valueOfEqualsFlag(argv, "--port");
+    const devCommandFlag = flag("--dev-command") ?? valueOfEqualsFlag(argv, "--dev-command");
+    const flagRefusal = previewFlagRefusal(portFlag, devCommandFlag);
+    if (flagRefusal) {
+        for (const l of flagRefusal)
+            console.log(l);
+        process.exitCode = 1;
+        return;
+    }
+    let settings;
+    try {
+        settings = resolveSettings({
+            devCommand: devCommandFlag,
+            devPort: portFlag !== undefined ? Number(portFlag) : undefined,
+        }, await readSettings(settingsRoot), TEMPLATE_DEFAULTS, ["dev"]);
+    }
+    catch (err) {
+        if (!(err instanceof SettingsError))
+            throw err;
+        for (const l of settingsRefusal(err, "preview"))
+            console.log(l);
+        process.exitCode = 1;
+        return;
+    }
+    const devCommand = settings.devCommand.value;
+    const devPort = settings.devPort.value;
+    const localUrl = `http://localhost:${devPort}`;
+    for (const l of settingsBanner({
+        devCommand,
+        devCommandSource: sourceWords(settings.devCommand),
+        devPort,
+        devPortSource: sourceWords(settings.devPort),
+        reused: await isPortListening(devPort),
+    })) {
+        console.log(l);
+    }
+    const harnessListed = await listsHarness(settingsRoot);
+    if (!harnessListed)
+        for (const l of noDiagnosticsStatic())
+            console.log(l);
     // The gate is LOCAL and NOTHING IS ATTEMPTED: no spinner, no partial mint, no
     // session left in `pending`. The command stops before it touches the network.
     if (!(await currentToken())) {
-        for (const l of notSignedIn())
+        for (const l of notSignedIn(devCommand, localUrl))
             console.log(l);
-        process.exitCode = 1;
+        process.exitCode = EXIT.NOT_AUTHENTICATED;
         return;
     }
     const filterViewer = flag("--viewer");
@@ -510,10 +560,13 @@ async function preview() {
     const ui = new PreviewUi({
         print: (l) => console.log(l),
         now: () => Date.now(),
-        targetUrl: `http://localhost:${numFlag("--port") ?? 5173}`,
+        targetUrl: localUrl,
         color,
         filterTester,
         filterViewer,
+        devCommand,
+        portSource: settings.devPort.source,
+        harnessListed,
     });
     // A preview already running for this folder — in ANOTHER process — is
     // FOLLOWED, not superseded. `vincentt preview` in a folder with a live
@@ -553,7 +606,9 @@ async function preview() {
     let running;
     try {
         const started = await previewStart(cwd, (m) => console.error(`[preview] ${m}`), {
-            appPort: numFlag("--port"),
+            appPort: devPort,
+            devCommand,
+            onHiddenPath: (p) => ui.hiddenPath(p),
             appStdio: has("--verbose") ? "inherit" : "ignore",
             onViewer: (label, uaClass) => ui.viewerSeen(label, uaClass),
             onViewerGone: (label) => ui.viewerGone(label),
@@ -591,7 +646,7 @@ async function preview() {
         const localOrg = await localOrgIdentity();
         for (const l of previewFailureLines(err, localOrg))
             console.log(l);
-        process.exitCode = 1;
+        process.exitCode = err instanceof AuthExpiredError ? EXIT.NOT_AUTHENTICATED : 1;
         return;
     }
     const qr = shouldRenderQr({
@@ -632,9 +687,24 @@ async function preview() {
     if (ending !== null) {
         ui.endedBy(ending, (await activeOrgName()) || "your workspace");
         await previewStop();
-        process.exitCode = 1;
+        process.exitCode = ending === "auth_expired" ? EXIT.NOT_AUTHENTICATED : 1;
     }
 }
+/** A `--port` or `--dev-command` value the schema refuses, before anything runs. */
+function previewFlagRefusal(port, devCommand) {
+    const portMessage = port === undefined
+        ? undefined
+        : validateField("dev.port", /^\d+$/.test(port) ? Number(port) : Number.NaN);
+    const commandMessage = devCommand === undefined ? undefined : validateField("dev.command", devCommand);
+    const bad = portMessage
+        ? `--port ${portMessage}`
+        : commandMessage
+            ? `--dev-command ${commandMessage}`
+            : undefined;
+    if (!bad)
+        return undefined;
+    return ["", `✗ ${bad}.`, "", "  Nothing was started.", ""];
+}
 /**
  * Flow L16 — follow a preview running in another terminal.
  *
@@ -657,7 +727,7 @@ async function followPreview(info, ui, filterTester, filterViewer) {
         console.log("✓ Following this preview");
     }
     console.log("");
-    const relay = httpRelayClient(`http://localhost:${info.relayPort}`);
+    const relay = httpRelayClient(`http://127.0.0.1:${info.relayPort}`);
     let since = -1;
     let warnedMissing = false;
     let stop = false;
@@ -762,6 +832,8 @@ async function projectConsoleUrl(cwd, sessionId) {
  * or an outage — a creator cannot act on that.
  */
 function previewFailureLines(err, local) {
+    if (err instanceof AuthExpiredError)
+        return authExpiredLines();
     if (err instanceof PreviewRateLimitedError)
         return mintRateLimited(err.retryAfterSec);
     // The ceiling is the second 409 on the mint route, and it is a DIFFERENT
@@ -1057,6 +1129,12 @@ async function dx() {
             : await dxDisableCommand(deps);
         return;
     }
+    if (options.sinceInvalid !== undefined) {
+        for (const l of sinceUsageLines(options.sinceInvalid))
+            console.error(l);
+        process.exitCode = EXIT.FAILED;
+        return;
+    }
     // Read strictly and independently of auth: a truncated config must disable the
     // relaxation, not throw through it.
     const enablement = await loadEnablement(now);
@@ -1222,7 +1300,7 @@ async function assets() {
  * the act does not exist: certificates renew on their own.
  */
 async function domain() {
-    const { domainCommand, resolveSub, } = await import("../domain/command.js");
+    const { domainCommand, resolveSub } = await import("../domain/command.js");
     const domainCopy = await import("../domain/copy.js");
     const api = await import("../domain/api.js");
     const sub = positional(1);
@@ -1246,11 +1324,7 @@ async function domain() {
     }
     const cwd = projectDir();
     const machine = await loadMachineConfig();
-    const config = async () => {
-        const apiUrl = process.env.VINCENTT_API_URL ?? machine.apiUrl ?? DEFAULT_API_URL;
-        const pat = process.env.VINCENTT_PAT ?? machine.pat;
-        return pat ? { apiUrl: apiUrl.replace(/\/$/, ""), pat } : undefined;
-    };
+    const config = async () => machineCredentials(machine);
     process.exitCode = await domainCommand({
         print: (l) => console.log(l),
         config,
@@ -1468,9 +1542,7 @@ async function announceBehind() {
         }
         if (needsRefresh(loadReleaseCache(), Date.now())) {
             refreshReleaseCache({
-                apiUrl: process.env.VINCENTT_API_URL ??
-                    (await loadMachineConfig()).apiUrl ??
-                    DEFAULT_API_URL,
+                apiUrl: machineApiUrl(await loadMachineConfig()),
                 now: () => Date.now(),
             });
         }
@@ -1506,6 +1578,20 @@ main()
     journal(Number(process.exitCode ?? 0));
 })
     .catch((err) => {
+    // A signed-out or refused token that no verb handled still exits with the
+    // not-signed-in code and the login remedy, so an agent has one code to branch on.
+    if (err instanceof NotSignedInError) {
+        for (const l of NOT_SIGNED_IN_LINES)
+            console.error(l);
+        journal(EXIT.NOT_AUTHENTICATED, err);
+        process.exit(EXIT.NOT_AUTHENTICATED);
+    }
+    if (isAuthRefused(err)) {
+        for (const l of authExpiredLines())
+            console.error(l);
+        journal(EXIT.NOT_AUTHENTICATED, err);
+        process.exit(EXIT.NOT_AUTHENTICATED);
+    }
     console.error(`\n✗ ${err instanceof Error ? err.message : String(err)}`);
     journal(1, err);
     process.exit(1);