@yolo-labs/yolo-cli 0.42.1 → 0.44.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,57 +1,66 @@
1
- # @yololabs/yolo-cli — YOLO Studio substrate CLI
1
+ # @yolo-labs/yolo-cli
2
2
 
3
- The `yolo` binary owns substrate-tooling subcommands (Plan import/export,
4
- future workspace and artifact primitives). Distinct from:
5
-
6
- - **`yolo-code`** — YOLO Studio's built-in coding agent CLI (separate package).
7
- - **`yolo-router`** — the LLM gateway client (separate package).
8
-
9
- ## Status
10
-
11
- Phase 8a Group 9 scaffold. v1 ships only `yolo --version` and
12
- `yolo context` (resolves and prints the container ambient session
13
- context). Plan import/export lands in Phase 8c.
14
-
15
- ## Usage (in-container)
3
+ The `yolo` CLI provides workspace context, artifact reads, personal app development
4
+ and publishing, and hosting commands. Run `yolo --help` for all commands.
16
5
 
17
6
  ```sh
18
- yolo --version
19
7
  yolo context
8
+ yolo artifact list
9
+ yolo tileapp init my-app
10
+ yolo deploy --dry-run
20
11
  ```
21
12
 
22
- Outside a Studio container the CLI exits with `session-required`. A future
23
- external-login flow is planned but out of scope for Phase 8.
13
+ Authenticated commands require `SESSION_ID`, `YOLO_COMMON_API_URL` (or
14
+ `YOLO_API_URL`), and a user access JWT. The CLI reads the rotated token at
15
+ `~/.config/yolo/token`, falling back to `YOLO_API_TOKEN`. The session record
16
+ supplies the workspace identity.
24
17
 
25
- ## Auth contract
18
+ Artifact commands mint a scoped delegated token through
19
+ `POST /internal/mcp/tokens`; hosting commands authenticate with the user JWT.
20
+ Offline commands such as app scaffolding, validation, and local serving do not
21
+ require authentication.
26
22
 
27
- Requires:
23
+ Build and test locally:
28
24
 
29
- - `SESSION_ID` (load-bearing — workspace derives from the session record)
30
- - `YOLO_COMMON_API_URL` (or `YOLO_API_URL`)
31
- - A credential — resolved by precedence (AUTH_AND_ONBOARDING Slice 0):
32
- 1. `~/.config/yolo/token` — the rotated **user access JWT**, rewritten
33
- every ~10 min by container-api's token-refresh service. Preferred;
34
- reading the file (not the env var) avoids the stale-shell problem.
35
- 2. `YOLO_API_TOKEN` env — the pod-injected user JWT (≤24h).
36
- 3. `INTERNAL_API_KEY` env — service master-key fallback, kept for
37
- lane-runner / service callers. **No longer required in user shells**
38
- and intentionally excluded from the sandbox env.
25
+ ```sh
26
+ npm ci
27
+ npm test
28
+ node dist/cli.js --help
29
+ ```
30
+
31
+ This standalone package is installed in Studio containers through
32
+ `containers/sandboxes/yolo-main/Dockerfile`.
39
33
 
40
- The CLI mints a short-lived delegated MCP token via the session-bound
41
- endpoint (`POST /internal/mcp/tokens`) with `agentId: 'substrate-cli'`
42
- and a capped scope set, authenticating with the user JWT
43
- (`Authorization: Bearer`) when available, falling back to
44
- `X-Internal-Auth` otherwise. It then calls `/internal/work/*` REST
45
- routes with the delegated bearer (which is the capability — the
46
- service header is no longer required by `requireMcpAuth`).
34
+ ## Managed branch previews
47
35
 
48
- ## Local build
36
+ Inside a Studio workspace, create a persistent preview of a repository branch:
49
37
 
50
38
  ```sh
51
- npm install
52
- npm run build
53
- node dist/cli.js --version
39
+ yolo preview create --name 'Latest main' --branch main --cwd web \
40
+ --setup 'npm ci' --build 'npm run build' \
41
+ --command 'npm start -- --hostname "$HOST" --port "$PORT"'
42
+ yolo preview status
43
+ yolo preview status <tile-id> --json
44
+ yolo preview logs <tile-id> --tail 100
45
+ yolo preview stop <tile-id>
54
46
  ```
55
47
 
56
- Standalone package — not a workspace member. Container install is an
57
- explicit `COPY` + `npm install -g` block in `containers/sandboxes/yolo-main/Dockerfile`.
48
+ Choose commands appropriate to your app; the example assumes its start script
49
+ accepts `--hostname` and `--port`. Single-quote commands to preserve `$PORT` and
50
+ `$HOST` for the service. It uses isolated checkouts, checks candidate health, and
51
+ switches the tile's stable port only after a successful build and start. Failed
52
+ updates keep the last working version. The required runtime must already be
53
+ installed; this service targets stateless HTTP apps, not database migrations.
54
+
55
+ The session resolves the authoritative workspace. Preview operations use delegated
56
+ capabilities; no manual credentials or workspace ID are needed. `create` returns
57
+ the tile ID and starts asynchronously. Use `status` for progress, and reuse
58
+ `--request-id <stable-id>` if retrying creation after an uncertain response.
59
+ `status` without an ID lists managed branch previews only. `stop` retains the tile
60
+ and configuration in Studio, removes its running service, and prevents startup on
61
+ page reload. Click **Start** in the tile to resume. Logs are bounded and in-memory;
62
+ stopping the service discards them. All commands accept `--json`.
63
+
64
+ `yolo preview --help` lists polling, timeout, port and health-check options. New CLI,
65
+ API, agent-registry scopes and container-api versions must be deployed together;
66
+ older deployments return an error rather than run a different preview mode.
@@ -3,7 +3,7 @@
3
3
  *
4
4
  * Returns the latest version by default; `--version <n>` pins to a
5
5
  * specific version. Default summary renders metadata only (key,
6
- * version, type, producer, fingerprint, contentLength, createdAt).
6
+ * version, type, producer, contentLength, createdAt).
7
7
  * `--content` flag emits ONLY the artifact content body to stdout
8
8
  * (suitable for piping). `--json` emits the full record including
9
9
  * content.
@@ -81,8 +81,7 @@ export async function runArtifactGet(options) {
81
81
  // ─── Output formatting ────────────────────────────────────────────────────
82
82
  /**
83
83
  * Header with metadata — no content body. The producer block tells
84
- * the operator who emitted the artifact (agent + tile) and provenance
85
- * fingerprint for cross-run identity.
84
+ * the operator who emitted the artifact (agent + tile).
86
85
  */
87
86
  export function formatSummary(artifact, workspaceId) {
88
87
  const lines = [];
@@ -90,12 +89,6 @@ export function formatSummary(artifact, workspaceId) {
90
89
  lines.push(` type: ${artifact.artifactType}`);
91
90
  lines.push(` contentLength: ${artifact.contentLength}`);
92
91
  lines.push(` producedBy: ${artifact.producedByAgentId}${artifact.producedByTileId ? ` (tile ${artifact.producedByTileId})` : ''}`);
93
- if (artifact.producerType)
94
- lines.push(` producerType: ${artifact.producerType}`);
95
- if (artifact.producerId)
96
- lines.push(` producerId: ${artifact.producerId}`);
97
- if (artifact.fingerprint)
98
- lines.push(` fingerprint: ${artifact.fingerprint}`);
99
92
  if (artifact.refPath)
100
93
  lines.push(` refPath: ${artifact.refPath}`);
101
94
  lines.push(` createdAt: ${artifact.createdAt}`);
package/dist/cli.js CHANGED
@@ -1,13 +1,6 @@
1
1
  #!/usr/bin/env node
2
2
  /**
3
- * `yolo` — YOLO Studio substrate CLI (Phase 8a Group 9 scaffold).
4
- *
5
- * Owns substrate-tooling subcommands (plan import/export/validate;
6
- * future: workspace, artifact). v1 ships only `yolo --version` and
7
- * `yolo context`; full plan import/export lands in Phase 8c.
8
- *
9
- * NOT the agent CLI. The agent CLI is `yolo-code`. NOT the LLM router
10
- * client. The LLM router client is `yolo-router`.
3
+ * `yolo` — YOLO Studio workspace, artifact, app and hosting CLI.
11
4
  *
12
5
  * Auth contract (AUTH_AND_ONBOARDING Slice 0 — user-JWT-only):
13
6
  * `SESSION_ID` + `YOLO_COMMON_API_URL` + a USER ACCESS JWT, resolved by
@@ -20,8 +13,6 @@
20
13
  * binding is derived from the session record, not from env or args.
21
14
  */
22
15
  import { readSessionContext, formatContext, ContextResolutionError } from './context.js';
23
- import { validatePlanFile, formatErrors } from './plan-validate.js';
24
- import { runRunList, exitCodeForFailure as runListExitCode, } from './run-list.js';
25
16
  import { runArtifactGet, exitCodeForFailure as artifactGetExitCode, } from './artifact-get.js';
26
17
  import { runArtifactList, exitCodeForFailure as artifactListExitCode, } from './artifact-list.js';
27
18
  import { runTileAppSign, runTileAppPublish, exitCodeForFailure as tileAppExitCode, } from './tileapp-publisher.js';
@@ -37,6 +28,7 @@ import { runTileAppSign, runTileAppPublish, exitCodeForFailure as tileAppExitCod
37
28
  // `../package.json` relative path resolves correctly both during
38
29
  // tests (src/) and in production (dist/).
39
30
  import { createRequire } from 'module';
31
+ import { exitAfterFlush } from './exit.js';
40
32
  const PKG_VERSION = createRequire(import.meta.url)('../package.json').version;
41
33
  /**
42
34
  * Serialize an orchestration result for `--json` output. Strips the
@@ -55,11 +47,6 @@ function printHelp() {
55
47
  '',
56
48
  'Commands:',
57
49
  ' context Print resolved session/workspace/API context.',
58
- ' plan validate <file> Validate a .yolo/plans/<slug>.md plan file (offline).',
59
- ' run list [opts] List Plan Runs in the current workspace (work.list_runs).',
60
- ' [--workspace <wsId>] Sanity-check the workspace bound to this session.',
61
- ' [--state <pending|running|paused|...>] Server-side executionState filter.',
62
- ' [--json] Pretty-print raw JSON instead of the table.',
63
50
  ' artifact get <key> [opts] Read a workspace artifact (work.get_artifact).',
64
51
  ' [--version <n>] Pin to a specific version. Default: latest.',
65
52
  ' [--workspace <wsId>] Sanity-check the workspace bound to this session.',
@@ -70,6 +57,11 @@ function printHelp() {
70
57
  ' [--limit <n>] Cap result count (1-500, default 100).',
71
58
  ' [--workspace <wsId>] Sanity-check the workspace bound to this session.',
72
59
  ' [--json] Pretty-print raw JSON instead of the table.',
60
+ ' kanban export <tileId> [opts] Read a board out as a seed document (operator-only REST route).',
61
+ ' [-o <file>] Write to <file>; refuses to overwrite. Default: stdout, for piping.',
62
+ ' [--workspace <wsId>] Sanity-check the workspace bound to this session.',
63
+ ' kanban import <boardId> <file> Rebuild a board from a seed document (additive; never overwrites).',
64
+ ' [--workspace <wsId>] Sanity-check the workspace bound to this session.',
73
65
  ' tileapp init <name> Scaffold a personal app (./<name>/tileapp.json + index.html).',
74
66
  ' tileapp validate <manifest> [opts] Offline lint: manifest schema + bundle layout (no auth).',
75
67
  ' tileapp media push <manifest> [--dir d] Upload store screenshots (additive — leaves the rest of the bundle alone).',
@@ -100,7 +92,8 @@ function printHelp() {
100
92
  ' mcp scopes [opts] Show mintable vs not-mintable MCP scopes for this session (pure read).',
101
93
  ' [--agent <agentId>] Agent identity to inspect (default: substrate-cli).',
102
94
  ' [--json] Emit {agentId, allowed, denied} as JSON.',
103
- ' serve <dir> [opts] Static file server (decision-preview / Gap 2a).',
95
+ ' preview <create|status|logs|stop> [opts] Manage branch-following previews.',
96
+ ' serve <dir> [opts] Static file server.',
104
97
  ' [--port <n>] Port (default: $PORT, else 3000).',
105
98
  ' [--host <h>] Bind host (default: 0.0.0.0).',
106
99
  ' [--spa] Serve index.html for unmatched routes (SPA mode).',
@@ -112,7 +105,7 @@ function printHelp() {
112
105
  ' deploy status [--json] Project + release status (incl. pending approvals).',
113
106
  ' deploy logs [--tail] [--since <dur>] Recent logs; --tail streams NDJSON.',
114
107
  ' deploy rollback [releaseId] [--json] Repoint the project to a previous release.',
115
- ' --version Print substrate CLI version.',
108
+ ' --version Print CLI version.',
116
109
  ' --help Print this help.',
117
110
  '',
118
111
  'Distinct from:',
@@ -121,30 +114,6 @@ function printHelp() {
121
114
  '',
122
115
  ].join('\n'));
123
116
  }
124
- function runPlanValidate(args) {
125
- const file = args[0];
126
- if (!file) {
127
- process.stderr.write('yolo: plan validate requires a file path\n');
128
- process.stderr.write('Usage: yolo plan validate <file>\n');
129
- return 64; // EX_USAGE
130
- }
131
- let result;
132
- try {
133
- result = validatePlanFile(file);
134
- }
135
- catch (err) {
136
- const msg = err instanceof Error ? err.message : String(err);
137
- process.stderr.write(`yolo: cannot read plan file '${file}': ${msg}\n`);
138
- return 64;
139
- }
140
- if (result.ok) {
141
- process.stdout.write(`OK: ${file} is canonical and schema-valid (planId=${result.planId}, ${result.bytes} bytes)\n`);
142
- return 0;
143
- }
144
- process.stderr.write(`FAIL: ${file}\n`);
145
- process.stderr.write(`${formatErrors(result.errors)}\n`);
146
- return 1;
147
- }
148
117
  function tileAppUsage(sub, message) {
149
118
  process.stderr.write(`yolo tileapp ${sub}: ${message}\n`);
150
119
  const usage = {
@@ -169,7 +138,7 @@ async function runTileAppInstallCmd(args) {
169
138
  const a = args[i];
170
139
  // A following flag must never be consumed as a value (`--workspace
171
140
  // --accept-optional=x`), so reject empty values and `--`-leading values —
172
- // same pattern as the run/plan parsers (codex gpt-5.6-sol P3, 2026-07-18).
141
+ // Reject flags in value positions.
173
142
  if (a === '--workspace') {
174
143
  const v = args[++i];
175
144
  if (!v || v.startsWith('--'))
@@ -540,61 +509,6 @@ async function runTileAppDevCmd(args) {
540
509
  }
541
510
  return runTileAppDev({ manifestPath, port, host, bundleDir, allow });
542
511
  }
543
- function parseRunListArgs(args) {
544
- let workspaceFlag;
545
- let stateFilter;
546
- let jsonOutput = false;
547
- for (let i = 0; i < args.length; i++) {
548
- const a = args[i];
549
- if (a === '--workspace') {
550
- const v = args[++i];
551
- if (!v || v.startsWith('--'))
552
- return { ok: false, message: '--workspace requires a value' };
553
- workspaceFlag = v;
554
- }
555
- else if (a.startsWith('--workspace=')) {
556
- workspaceFlag = a.slice('--workspace='.length);
557
- }
558
- else if (a === '--state') {
559
- const v = args[++i];
560
- if (!v || v.startsWith('--'))
561
- return { ok: false, message: '--state requires a value' };
562
- stateFilter = v;
563
- }
564
- else if (a.startsWith('--state=')) {
565
- stateFilter = a.slice('--state='.length);
566
- }
567
- else if (a === '--json') {
568
- jsonOutput = true;
569
- }
570
- else if (a.startsWith('--')) {
571
- return { ok: false, message: `unknown option: ${a}` };
572
- }
573
- else {
574
- return { ok: false, message: `unexpected positional argument: ${a}` };
575
- }
576
- }
577
- return { ok: true, workspaceFlag, stateFilter, jsonOutput };
578
- }
579
- async function runRunListCmd(args) {
580
- const parsed = parseRunListArgs(args);
581
- if (!parsed.ok) {
582
- process.stderr.write(`yolo: run list: ${parsed.message}\n`);
583
- process.stderr.write('Usage: yolo run list [--workspace <wsId>] [--state <pending|running|paused|succeeded|failed|cancelled|superseded>] [--json]\n');
584
- return 64;
585
- }
586
- const result = await runRunList({
587
- workspaceFlag: parsed.workspaceFlag,
588
- stateFilter: parsed.stateFilter,
589
- outputFormat: parsed.jsonOutput ? 'json' : 'summary',
590
- });
591
- if (result.ok) {
592
- process.stdout.write(`${result.output}\n`);
593
- return 0;
594
- }
595
- process.stderr.write(`FAIL [${result.kind}]: ${result.message}\n`);
596
- return runListExitCode(result.kind);
597
- }
598
512
  function parseArtifactGetArgs(args) {
599
513
  let key;
600
514
  let version;
@@ -781,32 +695,6 @@ async function main(argv) {
781
695
  throw err;
782
696
  }
783
697
  }
784
- if (cmd === 'plan') {
785
- const sub = args[1];
786
- if (sub === 'validate') {
787
- return runPlanValidate(args.slice(2));
788
- }
789
- if (!sub) {
790
- process.stderr.write('yolo: plan requires a subcommand (validate)\n');
791
- return 64;
792
- }
793
- process.stderr.write(`yolo: unknown plan subcommand '${sub}'\n`);
794
- process.stderr.write('Subcommands: validate\n');
795
- return 64;
796
- }
797
- if (cmd === 'run') {
798
- const sub = args[1];
799
- if (sub === 'list') {
800
- return runRunListCmd(args.slice(2));
801
- }
802
- if (!sub) {
803
- process.stderr.write('yolo: run requires a subcommand (list)\n');
804
- return 64;
805
- }
806
- process.stderr.write(`yolo: unknown run subcommand '${sub}'\n`);
807
- process.stderr.write('Subcommands: list\n');
808
- return 64;
809
- }
810
698
  if (cmd === 'artifact') {
811
699
  const sub = args[1];
812
700
  if (sub === 'get') {
@@ -849,6 +737,10 @@ async function main(argv) {
849
737
  process.stderr.write('Subcommands: init, validate, dev, sign, publish, media, install, add-tile\n');
850
738
  return 64;
851
739
  }
740
+ if (cmd === 'kanban') {
741
+ const { runKanbanCmd } = await import('./kanban-cli.js');
742
+ return runKanbanCmd(args.slice(1));
743
+ }
852
744
  if (cmd === 'mcp') {
853
745
  const sub = args[1];
854
746
  if (sub === 'scopes')
@@ -861,13 +753,17 @@ async function main(argv) {
861
753
  process.stderr.write('Subcommands: scopes\n');
862
754
  return 64;
863
755
  }
756
+ if (cmd === 'preview') {
757
+ const { runPreviewCmd } = await import('./preview.js');
758
+ return runPreviewCmd(args.slice(1));
759
+ }
864
760
  if (cmd === 'serve') {
865
761
  const { runServeCmd } = await import('./serve.js');
866
762
  return runServeCmd(args.slice(1));
867
763
  }
868
764
  if (cmd === 'deploy') {
869
765
  // Lazy-load (serve precedent) so the deploy stack — incl. esbuild via
870
- // deploy-bundle — never taxes `yolo plan` startup.
766
+ // deploy-bundle is loaded only for hosting commands.
871
767
  const { runDeployCmd } = await import('./deploy-cli.js');
872
768
  return runDeployCmd(args.slice(1));
873
769
  }
@@ -875,7 +771,9 @@ async function main(argv) {
875
771
  printHelp();
876
772
  return 64; // EX_USAGE
877
773
  }
878
- main(process.argv).then((code) => process.exit(code), (err) => {
774
+ // Never `process.exit()` straight after writing: output to a pipe is async and
775
+ // would be cut at the 64 KiB pipe buffer (see ./exit.ts).
776
+ main(process.argv).then((code) => exitAfterFlush(code), (err) => {
879
777
  process.stderr.write(`yolo: unexpected error: ${err?.message ?? err}\n`);
880
- process.exit(1);
778
+ exitAfterFlush(1);
881
779
  });
@@ -3,7 +3,7 @@
3
3
  * (docs/MANAGED_HOSTING_CLI_SPEC.md §1).
4
4
  *
5
5
  * yolo deploy [--env <staging|prod>] [--dry-run] [--json] ← bare = ship
6
- * yolo deploy init [--slug <slug>] [--type <static|worker>] [--parent <id|slug>] [--json]
6
+ * yolo deploy init [--slug <slug>] [--type <static|worker>] [--parent <id|slug> | --no-parent] [--json]
7
7
  * yolo deploy status [--json]
8
8
  * yolo deploy logs [--tail] [--since <dur>] [--json]
9
9
  * yolo deploy rollback [releaseId] [--json]
@@ -36,14 +36,14 @@ function defaultStatPath(p) {
36
36
  }
37
37
  import { runDeployShip, exitCodeForFailure, formatShipSuccess, formatPending, formatFail, } from './deploy-ship.js';
38
38
  import { resolveDeployContext, createProject, getProjectStatus, listProjects, rollbackProject, unpublishProject, republishProject, renameProject, setProjectParent, addAlias, removeAlias, setRedirect, deleteProject, cloneProject, getLogs, pollTail, queryD1, } from './deploy-client.js';
39
- import { readDeployConfig, writeDeployConfig } from './deploy-config.js';
39
+ import { readDeployConfig, writeDeployConfig, findAncestorDeployLink as findAncestorLink, } from './deploy-config.js';
40
40
  import { adaptWrangler, detectProjectShape } from './deploy-detect.js';
41
41
  import { collectNodeBuiltinsFromText } from './deploy-bundle.js';
42
42
  import { runDeployDev } from './deploy-dev.js';
43
43
  import { defaultReadFile } from './auth-context.js';
44
44
  const USAGE = [
45
45
  'Usage: yolo deploy [--env <staging|prod>] [--dry-run] [--json]',
46
- ' yolo deploy init [--slug <slug>] [--type <static|worker>] [--parent <id|slug>] [--json]',
46
+ ' yolo deploy init [--slug <slug>] [--type <static|worker>] [--parent <id|slug> | --no-parent] [--json]',
47
47
  ' yolo deploy link (--project-id <id> | --slug <slug>) [--type <static|worker>]',
48
48
  ' yolo deploy validate [--json]',
49
49
  ' yolo deploy doctor [--json]',
@@ -200,6 +200,7 @@ export function parseInitArgs(args) {
200
200
  let slug;
201
201
  let type;
202
202
  let parentProjectId;
203
+ let noParent = false;
203
204
  let jsonOutput = false;
204
205
  for (let i = 0; i < args.length; i++) {
205
206
  const a = args[i];
@@ -229,6 +230,9 @@ export function parseInitArgs(args) {
229
230
  return { ok: false, message: '--parent requires a project id' };
230
231
  parentProjectId = v;
231
232
  }
233
+ else if (a === '--no-parent') {
234
+ noParent = true;
235
+ }
232
236
  else if (a.startsWith('--parent=')) {
233
237
  parentProjectId = a.slice('--parent='.length);
234
238
  }
@@ -248,7 +252,12 @@ export function parseInitArgs(args) {
248
252
  if (parentProjectId !== undefined && parentProjectId.length === 0) {
249
253
  return { ok: false, message: '--parent requires a project id or slug' };
250
254
  }
251
- return { ok: true, slug, type, parentProjectId, jsonOutput };
255
+ // Refuse rather than pick a winner: the two flags express opposite intents,
256
+ // and silently honouring one would create a project the caller did not ask for.
257
+ if (noParent && parentProjectId !== undefined) {
258
+ return { ok: false, message: '--parent and --no-parent are mutually exclusive' };
259
+ }
260
+ return { ok: true, slug, type, parentProjectId, noParent, jsonOutput };
252
261
  }
253
262
  async function runInitCmd(args, deps, io) {
254
263
  const parsed = parseInitArgs(args);
@@ -268,6 +277,19 @@ async function runInitCmd(args, deps, io) {
268
277
  const cwd = deps.cwd ?? process.cwd();
269
278
  const readConfig = deps.readDeployConfigImpl ?? readDeployConfig;
270
279
  const writeConfig = deps.writeDeployConfigImpl ?? writeDeployConfig;
280
+ // 🚨 `deps.env` is a TEST SEAM, not the environment. The real CLI reaches here
281
+ // as `runDeployCmd(args)` with no deps at all (`cli.ts:739`), so `deps.env?.X`
282
+ // is always undefined in production — a shape that reads like an env lookup and
283
+ // silently is not one. `resolveDeployContext` already uses the `?? process.env`
284
+ // form; these two had not. Behind it were:
285
+ // - the ancestor walk's `$HOME` floor, which would have been DISABLED in
286
+ // production, permitting exactly the machine-wide capture it exists to stop;
287
+ // - `WORKSPACE_ID` on create, so a hosting project made by `yolo deploy init`
288
+ // inside a session pod has NEVER carried the `workspaceId` that routes deploy
289
+ // lifecycle events back to the workspace (and to VibeAssist watchers).
290
+ // Pre-existing, and dead since it shipped.
291
+ // Injection still wins, so tests are unaffected.
292
+ const env = deps.env ?? process.env;
271
293
  const readResult = readConfig(cwd);
272
294
  if (!readResult.ok) {
273
295
  // Never silently clobber a malformed/invalid link file.
@@ -283,7 +305,10 @@ async function runInitCmd(args, deps, io) {
283
305
  // 🚨 `--parent` on an ALREADY-LINKED directory would otherwise report
284
306
  // `already-linked` and exit 0, having silently ignored the flag — the same
285
307
  // false-success the slug-reconciliation guard below exists to prevent.
286
- // Parent links are create-only, so there is nothing `init` can do here.
308
+ // `init` itself can do nothing here — its parent link is create-only — but
309
+ // re-parenting IS possible since S5 (2026-08-09): `yolo deploy set-parent`.
310
+ // The advice below used to say there was no re-parent route at all, which
311
+ // sent people to recreate a project when one command would have done.
287
312
  const message = 'this directory is already linked to a project; --parent only applies when creating one';
288
313
  // JSON mode keeps stderr EMPTY — automation treats it as diagnostics, and
289
314
  // the init contract is a clean stream split.
@@ -295,8 +320,8 @@ async function runInitCmd(args, deps, io) {
295
320
  // Only advice that actually works: parent links are create-only and
296
321
  // there is no re-parent route or console control, so the recovery is
297
322
  // to create the child as a NEW project.
298
- + ' Nesting is set at creation. Create the child in its own directory with\n'
299
- + ' `yolo deploy init --parent <id|slug>`, or from the Hosting console\'s New project dialog.\n');
323
+ + ' To re-parent THIS project: `yolo deploy set-parent <id|slug>`.\n'
324
+ + ' To create a NEW child: `yolo deploy init --parent <id|slug>` in its own directory.\n');
300
325
  }
301
326
  return 1;
302
327
  }
@@ -358,6 +383,44 @@ async function runInitCmd(args, deps, io) {
358
383
  // Else: not a slug of ours, but id-shaped — pass through and let the
359
384
  // server's ownership-asserted read be the authority.
360
385
  }
386
+ // ── Inferred parent (nesting §10 S4) ────────────────────────────────────
387
+ // No `--parent` given: look UP for an ancestor that is already a hosting
388
+ // project. `yolo deploy init` inside `apps/api` otherwise mints a fully
389
+ // independent project named after the directory — which is exactly how
390
+ // `El Paso Ballroom API` came to sit as an unrelated top-level card beside the
391
+ // site it serves. The relationship already exists in the filesystem; this
392
+ // records it.
393
+ //
394
+ // 🚨 INFERRED IS BEST-EFFORT; EXPLICIT IS AUTHORITATIVE. An inference must
395
+ // never fail an `init` that would otherwise succeed, so the candidate is
396
+ // VALIDATED against the caller's own projects before use and simply dropped if
397
+ // it does not qualify. A bad `--parent`, by contrast, still fails loudly above
398
+ // — the user asked for that specific parent and did not get it.
399
+ let inferredParent;
400
+ if (!resolvedParentId && !parsed.noParent) {
401
+ const ancestor = findAncestorLink(cwd, deps.readFileImpl, { ...(env.HOME ? { home: env.HOME } : {}) });
402
+ if (ancestor) {
403
+ const listImpl = deps.listProjectsImpl ?? listProjects;
404
+ const listed = await listImpl(auth.context);
405
+ // A list failure is NOT a reason to fail: we are only looking for a
406
+ // default. Fall through and create a root.
407
+ if (listed.ok) {
408
+ const match = listed.value.find((p) => resolveProjectId(p) === ancestor.projectId);
409
+ // Roots only, and only a project in a state the server will accept as a
410
+ // parent — the same rule the console's picker applies. Anything else is
411
+ // dropped silently: it is a suggestion, not an instruction.
412
+ const parentOfParent = match ? match.parentProjectId : undefined;
413
+ const status = match ? str(match.status) : undefined;
414
+ const eligible = !!match
415
+ && (parentOfParent === null || parentOfParent === undefined)
416
+ && (status === undefined || status === 'active' || status === 'published');
417
+ if (eligible) {
418
+ resolvedParentId = ancestor.projectId;
419
+ inferredParent = { link: ancestor, ...(str(match.slug) ? { slug: str(match.slug) } : {}) };
420
+ }
421
+ }
422
+ }
423
+ }
361
424
  const create = deps.createProjectImpl ?? createProject;
362
425
  const created = await create(auth.context, {
363
426
  name: parsed.slug ?? path.basename(cwd),
@@ -366,7 +429,7 @@ async function runInitCmd(args, deps, io) {
366
429
  // lets server-side deploy lifecycle events route back to the workspace
367
430
  // (and therefore to VibeAssist event watchers). Local CLI use remains
368
431
  // unchanged because the field is optional.
369
- ...(deps.env?.WORKSPACE_ID ? { workspaceId: deps.env.WORKSPACE_ID } : {}),
432
+ ...(env.WORKSPACE_ID ? { workspaceId: env.WORKSPACE_ID } : {}),
370
433
  // Nesting S4 — passed straight through; the server verifies ownership,
371
434
  // depth and parent state. Not written to `.yolo/deploy.json`.
372
435
  ...(resolvedParentId ? { parentProjectId: resolvedParentId } : {}),
@@ -399,6 +462,21 @@ async function runInitCmd(args, deps, io) {
399
462
  && str(owned?.parentProjectId)?.toLowerCase()
400
463
  !== resolvedParentId?.toLowerCase();
401
464
  if (projectId && !parentMismatch) {
465
+ // 🚨 An INFERRED parent must not silently evaporate here (codex P2).
466
+ // Reconciliation is still right — refusing would strand a project the
467
+ // caller already owns, which `init` must never do, and parent links
468
+ // are create-only so this path cannot apply one. But the caller was
469
+ // about to get a nested project and is instead getting a link to an
470
+ // existing one that may sit elsewhere in the tree. Say so, and name
471
+ // the command that closes the gap.
472
+ const existingParent = str(owned?.parentProjectId);
473
+ const inferenceLost = !!inferredParent
474
+ && existingParent?.toLowerCase() !== resolvedParentId?.toLowerCase();
475
+ if (inferenceLost && !parsed.jsonOutput) {
476
+ io.out(`note: this project already existed and is NOT under ${inferredParent.slug ?? resolvedParentId}.\n`
477
+ + ` Nesting was inferred from ${inferredParent.link.path} but only applies when creating.\n`
478
+ + ` Run \`yolo deploy set-parent ${inferredParent.slug ?? resolvedParentId}\` to nest it.\n`);
479
+ }
402
480
  return writeLinkFile(cwd, writeConfig, io, {
403
481
  projectId,
404
482
  slug: str(owned.slug) ?? takenSlug,
@@ -407,6 +485,9 @@ async function runInitCmd(args, deps, io) {
407
485
  adapted,
408
486
  jsonOutput: parsed.jsonOutput,
409
487
  jsonStatus: 'linked-existing',
488
+ // Machine callers get the same fact as a field, never a claim
489
+ // that the nesting happened.
490
+ ...(inferenceLost ? { parentNotApplied: resolvedParentId } : {}),
410
491
  }, `OK: slug '${takenSlug}' was already yours — linked existing project ${projectId} — wrote .yolo/deploy.json`);
411
492
  }
412
493
  }
@@ -429,7 +510,29 @@ async function runInitCmd(args, deps, io) {
429
510
  io.err(`${formatFail(failure)}\n`);
430
511
  return 2;
431
512
  }
432
- return writeLinkFile(cwd, writeConfig, io, { projectId, slug, type: parsed.type, existing, adapted, jsonOutput: parsed.jsonOutput, jsonStatus: 'created' }, `OK: linked project ${projectId}${slug ? ` (slug ${slug})` : ''} — wrote .yolo/deploy.json`);
513
+ // 🚨 SAY SO. A parent nobody asked for, applied silently, is the worst
514
+ // outcome available here — the caller would only discover the nesting from
515
+ // the console. Human mode names the ancestor file it came from and the exact
516
+ // command to undo it; JSON mode carries the same facts as fields.
517
+ if (inferredParent && !parsed.jsonOutput) {
518
+ const label = inferredParent.slug ? `${inferredParent.slug} (${resolvedParentId})` : resolvedParentId;
519
+ io.out(`note: nested under ${label}, inferred from ${inferredParent.link.path}\n`
520
+ + ' Use --no-parent to create a top-level project instead,\n'
521
+ + ' or `yolo deploy set-parent --none` to detach this one.\n');
522
+ }
523
+ return writeLinkFile(cwd, writeConfig, io, {
524
+ projectId,
525
+ slug,
526
+ type: parsed.type,
527
+ existing,
528
+ adapted,
529
+ jsonOutput: parsed.jsonOutput,
530
+ jsonStatus: 'created',
531
+ ...(resolvedParentId ? { parentProjectId: resolvedParentId } : {}),
532
+ ...(inferredParent
533
+ ? { parentInferredFrom: inferredParent.link.path }
534
+ : {}),
535
+ }, `OK: linked project ${projectId}${slug ? ` (slug ${slug})` : ''} — wrote .yolo/deploy.json`);
433
536
  }
434
537
  export function parseLinkArgs(args) {
435
538
  let projectId;
@@ -1889,6 +1992,13 @@ function writeLinkFile(cwd, writeConfig, io, params, message) {
1889
1992
  ...(params.slug ? { slug: params.slug } : {}),
1890
1993
  ...(params.type ? { type: params.type } : {}),
1891
1994
  configPath: '.yolo/deploy.json',
1995
+ // Nesting is invisible in `.yolo/deploy.json` by design (the link lives
1996
+ // on the project document), so JSON callers would have no way to see it
1997
+ // happened. `parentInferredFrom` is present ONLY when the CLI chose the
1998
+ // parent — its absence means the caller asked for it or there is none.
1999
+ ...(params.parentProjectId ? { parentProjectId: params.parentProjectId } : {}),
2000
+ ...(params.parentInferredFrom ? { parentInferredFrom: params.parentInferredFrom } : {}),
2001
+ ...(params.parentNotApplied ? { parentNotApplied: params.parentNotApplied } : {}),
1892
2002
  ...(params.adapted
1893
2003
  ? { adapted: { sourceFile: params.adapted.sourceFile, migrated: params.adapted.migrated, warnings: params.adapted.warnings } }
1894
2004
  : {}),