@vincentt-xr/cli 0.1.5 → 0.3.0

package/README.md

@@ -0,0 +1,94 @@
+# @vincentt-xr/cli — `vincentt`
+
+The command-line dev loop for building AR/XR apps on Vincentt. You build a real
+React + react-three-fiber app locally with your own coding agent (Claude Code,
+Cursor, Codex) and this CLI drives the platform side: scaffold a project, preview
+it on a phone over a secure tunnel, read what the device reports back, and publish
+to `<slug>.vincentt.app`.
+
+Only prerequisite: Node.js (which provides `npx`). Nothing is installed globally.
+
+## Getting started (read this before running anything)
+
+If you are a coding agent that was asked to build a Vincentt AR app, follow this
+order. It matters:
+
+1. **Confirm a project name with the developer first.** Do not guess one, and do
+   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:**
+
+   ```
+   npx -y @vincentt-xr/cli@latest create --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.
+
+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
+   developer the project is ready and ask what they want to make. Build only once
+   they have described it.
+
+4. **When you start building,** `AGENTS.md` and `GROUNDING.md` (both in the
+   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
+idea.** Everything after first contact is driven from the project's own
+`AGENTS.md`.
+
+## Commands
+
+```
+Auth
+  login              Sign in; save an access token to ~/.vincentt/config.json
+  logout             Remove the saved access token
+  whoami             Show the signed-in account
+
+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]
+  network            fetch/XHR requests              [--json]
+  trace              Performance samples             [--json]
+
+Reverse channel
+  feedback --wait    Block for the next phone annotation, print it, exit
+  feedback --watch   Stream annotations as they arrive
+
+Servers
+  relay              Run the diagnostics/annotation relay
+  mcp                Run the MCP adapter (for hosts without a shell)
+
+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.
+
+## The loop, once a project exists
+
+- `pnpm dev` — local dev server at `http://localhost:5173`.
+- `npx vincentt preview` — build, serve, and tunnel the app so you get one `https`
+  URL (and a desktop QR page) to open on a phone. AR needs a secure context for
+  camera access, so this is how you test tracking and gestures on a device.
+- `npx vincentt logs | network | trace` — read what the phone reported to the
+  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 publish` — build (`pnpm build`), then upload the built `dist/` and
+  return the live `<slug>.vincentt.app` URL. Nothing builds server-side.
+
+`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

@@ -0,0 +1,14 @@
+/**
+ * True when the invocation is a request for help rather than an action — no
+ * command, or `--help`/`-h` anywhere in the args. The dispatcher checks this
+ * BEFORE routing to a verb so that `login --help`, `create --help`, etc. print
+ * usage instead of running the (side-effectful) verb.
+ */
+export declare function isHelpInvocation(args: string[]): boolean;
+export declare function refusedFlag(args: string[]): string | undefined;
+/**
+ * The bare arguments, with flag VALUES removed. Without this, `vincentt link --dir
+ * /tmp 66f1` reads `/tmp` as the project id — a wrong-but-plausible value, which is
+ * the worst kind for an identifier that decides which project a folder points at.
+ */
+export declare function positionalArgs(args: string[]): string[];

package/dist/cli/args.js

@@ -0,0 +1,51 @@
+/**
+ * True when the invocation is a request for help rather than an action — no
+ * command, or `--help`/`-h` anywhere in the args. The dispatcher checks this
+ * BEFORE routing to a verb so that `login --help`, `create --help`, etc. print
+ * usage instead of running the (side-effectful) verb.
+ */
+export function isHelpInvocation(args) {
+    return args[0] === undefined || args.includes("--help") || args.includes("-h");
+}
+/** Flags that stand alone; every other `--flag` consumes the next argument. */
+const BOOLEAN_FLAGS = new Set([
+    "--force",
+    "--preview",
+    "--json",
+    "--errors",
+    "--wait",
+    "--watch",
+    "--stop",
+    "--no-install",
+    "--allow-custom-api",
+    "--yes",
+    "--help",
+    "-h",
+]);
+/**
+ * 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
+ * writing to the creator's source is a named boundary.
+ */
+const REFUSED_FLAGS = new Set(["--fix", "--write-meta"]);
+export function refusedFlag(args) {
+    return args.find((a) => REFUSED_FLAGS.has(a.split("=")[0]));
+}
+/**
+ * The bare arguments, with flag VALUES removed. Without this, `vincentt link --dir
+ * /tmp 66f1` reads `/tmp` as the project id — a wrong-but-plausible value, which is
+ * the worst kind for an identifier that decides which project a folder points at.
+ */
+export function positionalArgs(args) {
+    const out = [];
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (!a.startsWith("-")) {
+            out.push(a);
+            continue;
+        }
+        if (!BOOLEAN_FLAGS.has(a) && !a.includes("="))
+            i++;
+    }
+    return out;
+}