@vincentt-xr/cli 0.9.0 → 0.10.0

package/README.md

@@ -17,16 +17,20 @@ order. It matters:
    not run `create` until you have it. The name becomes the live subdomain
    (`<slug>.vincentt.app`), so it is worth one question.
 
-2. **Scaffold the project:**
+2. **Create the project:**
 
    ```
-   npx -y @vincentt-xr/cli@latest create --name "<name>"
+   npx -y @vincentt-xr/cli@latest create <name> --name "<name>"
    ```
 
-   Run it in an empty directory. This binds a backend project and writes a
-   complete, runnable starter (an AR app that previews as-is). If you are not
-   signed in yet, the command opens a browser for the developer to approve once,
-   then continues. That is the only human step.
+   In an **empty** folder this writes a complete, runnable starter (an AR app that
+   previews as-is), installs its dependencies, and then registers the project and
+   reserves its address. In a folder that is already a Vincentt app it only
+   registers. In any other non-empty folder it refuses and says what to run.
+
+   The scaffolding half needs no account. The registering half does: if you are
+   not signed in yet, the command opens a browser for the developer to approve
+   once, then continues. That is the only human step.
 
 3. **Read `AGENTS.md` in the new project, then stop.** The scaffold is already a
    working starter. **Do not invent an app or start building a scene.** Tell the
@@ -37,25 +41,39 @@ order. It matters:
    project root) are the authoritative guides for the dev loop and the SDK API.
    Read the SDK reference at the point you write a scene, not before.
 
-The short version: **ask for a name, scaffold, confirm it is ready, wait for the
+The short version: **ask for a name, create, confirm it is ready, wait for the
 idea.** Everything after first contact is driven from the project's own
 `AGENTS.md`.
 
 ## Commands
 
+`init` needs no account, ever — the template is yours to scaffold and run locally
+whether or not you sign in. `create` also scaffolds an empty folder, and then
+registers the project, which is what needs an account.
+
 ```
 Auth
   login              Sign in; save an access token to ~/.vincentt/config.json
   logout             Remove the saved access token
   whoami             Show the signed-in account
 
+Project
+  init [dir]         Scaffold a Vincentt XR app — no account needed, ever
+                       [--no-install] [--template <version>]
+                       [--from <owner>/<repo>@<tag>]
+  create [name]      Register a project and reserve its address; scaffolds first
+                       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
+  unlink             Detach this directory from its project
+  projects           List the workspace's projects and their ids
+                       [--json] [--org <s>]
+
 Dev loop
-  create             Scaffold + bind a project (empty dir -> full starter)
-                       [--name <s>] [--slug <s>] [--preview] [--force]
   publish            Upload the built dist; go live at <slug>.vincentt.app
   preview            Serve + tunnel the app for on-device preview
                        (prints a desktop QR page to scan) [--stop]
-  unbind             Detach this directory from its project
 
 Diagnostics (need a running preview)
   logs [--errors]    Console logs from the device   [--json]
@@ -75,9 +93,10 @@ Meta
 Common options: --dir <path> (project dir, default cwd)
 ```
 
-Auth-needing verbs (`create`, `preview`, `publish`) fold sign-in into the first
-run: with no saved token they open the browser to authorize this device, then the
-token lives in `~/.vincentt/config.json` and later verbs run without prompting.
+Auth-needing verbs (`create`'s registering half, `preview`, `publish`) fold
+sign-in into the first run: with no saved token they open the browser to
+authorize this device, then the token lives in `~/.vincentt/config.json` and
+later verbs run without prompting. `init` never reaches that gate at all.
 
 ## The loop, once a project exists
 
@@ -89,8 +108,16 @@ token lives in `~/.vincentt/config.json` and later verbs run without prompting.
   preview relay. Debug on-device misbehavior instead of guessing.
 - `npx vincentt feedback --wait` — block for the next annotation the developer
   draws on the phone preview, print it as JSON, and exit.
+- `npx vincentt preview --stop` — stop a preview started from another terminal.
+  When the relay can still be reached it reports how many connections are
+  attached first, so nobody blanks four phones without seeing that they are
+  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.
 
+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>`
+needs. `--json` prints the same rows for a program to read.
+
 `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.

package/dist/cli/args.d.ts

@@ -32,6 +32,18 @@ export interface ArgConflict {
  * work begins. Returns the conflict to report, or undefined.
  */
 export declare function fromFlagConflict(args: string[]): ArgConflict | undefined;
+/**
+ * The offending flag on a `create` invocation, or undefined.
+ *
+ * The `.split("=")[0]` is load-bearing and is NOT what `flag()` does. `flag()` is a
+ * bare `argv.indexOf(name)`, which cannot see `--template=1.0.0` at all — copying
+ * its idiom here would let the equals spelling through in silence, which is the
+ * whole of the control. Case-SENSITIVE, deliberately: case-folding would turn
+ * `--TEMPLATE` into a flag that this refusal recognises and the rest of the CLI
+ * does not, i.e. a refusal for an input that was never going to work anyway, while
+ * teaching a reader that the two spellings are equivalent.
+ */
+export declare function createSourceFlagRefusal(args: string[]): string | undefined;
 export declare function refusedFlag(args: string[]): string | undefined;
 /**
  * The bare arguments, with flag VALUES removed. Without this, `vincentt link --dir

package/dist/cli/args.js

@@ -75,6 +75,46 @@ export function fromFlagConflict(args) {
     }
     return undefined;
 }
+/**
+ * Source-selecting flags `create` must never honor.
+ *
+ * `create` clones TEMPLATE_REPO at `latest` and nothing else, and the decision to
+ * INSTALL dependencies on the unauthenticated scaffold path rests entirely on that
+ * being structurally true (f6's S-1 refuses an install only for a repo WE DO NOT
+ * CONTROL; scoping it, rather than overriding it, requires that `create` cannot be
+ * pointed anywhere else).
+ *
+ * Refused HERE rather than by not reading the flag, for the same reason
+ * INSTALL_ENABLING_FLAGS is: `flag()` is a global argv scan with no per-verb gate,
+ * so honoring one is a one-line accident, while defeating this refusal means
+ * deleting it, which is a reviewable act.
+ *
+ * Same flag, same code, different blast radius: on `init` the scaffold IS the
+ * command and a creator typed the ref; on `create` the scaffold is a side effect on
+ * a path an agent drives. Do not "harmonize" these.
+ */
+const CREATE_REFUSED_SOURCE_FLAGS = new Set(["--from", "--template"]);
+/**
+ * The offending flag on a `create` invocation, or undefined.
+ *
+ * The `.split("=")[0]` is load-bearing and is NOT what `flag()` does. `flag()` is a
+ * bare `argv.indexOf(name)`, which cannot see `--template=1.0.0` at all — copying
+ * its idiom here would let the equals spelling through in silence, which is the
+ * whole of the control. Case-SENSITIVE, deliberately: case-folding would turn
+ * `--TEMPLATE` into a flag that this refusal recognises and the rest of the CLI
+ * does not, i.e. a refusal for an input that was never going to work anyway, while
+ * teaching a reader that the two spellings are equivalent.
+ */
+export function createSourceFlagRefusal(args) {
+    for (const a of args) {
+        if (!a.startsWith("-"))
+            continue;
+        const name = a.split("=")[0];
+        if (CREATE_REFUSED_SOURCE_FLAGS.has(name))
+            return name;
+    }
+    return undefined;
+}
 /**
  * Flags the CLI deliberately does NOT have. The checklist reports and never
  * writes: a suggested value is one keystroke from a tool that writes it, and

package/dist/cli/index.d.ts

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-export {};
+export declare function usage(): string;