@yolo-labs/yolo-cli 1.1.0 → 1.2.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/dist/cli.js CHANGED
@@ -76,10 +76,12 @@ function printHelp() {
76
76
  ' git doctor [opts] Diagnose why git (not gh) can\'t authenticate to github.com.',
77
77
  ' [--fix] Repair what is safe to (store file, helpers, remote URL), then re-check.',
78
78
  ' [--offline] [--remote <name>] [--json] Skip network checks; remote to probe (default: origin); JSON output.',
79
+ ' tileapp --help List the tileapp subcommands; `yolo tileapp <sub> --help` for one.',
79
80
  ' tileapp init <name> Scaffold a personal app (./<name>/tileapp.json + index.html).',
80
81
  ' tileapp validate <manifest> [opts] Offline lint: manifest schema + bundle layout (no auth).',
81
- ' tileapp media push <manifest> [--dir d] Upload store screenshots (additive — leaves the rest of the bundle alone).',
82
+ ' [--personal | --marketplace] Rules to apply (default: personal when `publisher` is absent or "personal").',
82
83
  ' [--bundle-dir <dir>] Override the static-bundle directory to check.',
84
+ ' tileapp media push <manifest> [--dir d] Upload store screenshots (additive — leaves the rest of the bundle alone).',
83
85
  ' tileapp dev <manifest> [opts] Serve the bundle locally + a mock broker (offline iterate).',
84
86
  ' [--port N] [--host H] Bind (default: 127.0.0.1:$PORT|3000).',
85
87
  ' [--bundle-dir <dir>] [--deny] Override bundle dir; --deny = mock broker denies all.',
@@ -92,6 +94,7 @@ function printHelp() {
92
94
  " 'worker'`): uploads the bundle incl. its _worker/ backend, no build.",
93
95
  ' [--live] Worker: run the backend live on Dynamic Workers (owner only, in-progress).',
94
96
  ' [--bundle-dir <dir>] Pure-UI: override the static-bundle directory to upload.',
97
+ ' [--include <path>] Upload a README*/*.md file that is skipped by default (repeatable).',
95
98
  ' [--context <dir>] [--dockerfile <f>] Runtime: build context + Dockerfile (default: the manifest dir).',
96
99
  ' [--builder auto|podman|skopeo] Runtime build engine. auto (default): skopeo assembler for RUN-less',
97
100
  ' Dockerfiles (no container engine — works in-pod), else podman.',
@@ -130,20 +133,51 @@ function printHelp() {
130
133
  '',
131
134
  ].join('\n'));
132
135
  }
136
+ /** One usage block per `yolo tileapp` subcommand: printed to stdout for `--help`, to stderr on a usage error. */
137
+ const TILEAPP_USAGE = {
138
+ init: 'Usage: yolo tileapp init <name>\n'
139
+ + ' Scaffold a personal app: ./<name>/tileapp.json + index.html + app.js + style.css.\n'
140
+ + ' The manifest has `id` (the app\'s local name) and no `publisher`: the server stamps it.\n',
141
+ sign: 'Usage: yolo tileapp sign <manifest.json> --publisher <id> [--key <keyId>] [--stdout]\n'
142
+ + ' KMS-sign a marketplace manifest (POST /v1/publisher/sign).\n',
143
+ publish: 'Usage: yolo tileapp publish <manifest.json> --personal [--bundle-dir <dir>] [--include <path>]... [--context <dir>] [--dockerfile <f>] [--builder auto|podman|skopeo] [--live] (personal app)\n'
144
+ + ' or: yolo tileapp publish <manifest.json> [--channel beta|stable] [--image-digest <d>] (marketplace)\n'
145
+ + ' Bundle files: dotfiles, node_modules/, README* and *.md / *.markdown files are NOT uploaded (the\n'
146
+ + ' bundle is served publicly) unless the file is surface.entry, is referenced by another uploaded\n'
147
+ + ' file, or is named with --include <path> (repeatable, relative to the bundle dir).\n'
148
+ + ' If the app is installed in this workspace, a new version moves that install to it\n'
149
+ + ' (when it asks for no new permissions); otherwise the output names the one command to run.\n',
150
+ validate: 'Usage: yolo tileapp validate <manifest.json> [--bundle-dir <dir>] [--personal | --marketplace]\n'
151
+ + ' Offline lint (no auth). Without a flag, a manifest with no `publisher` (or "personal") is\n'
152
+ + ' checked with the personal-app rules, any other publisher with the marketplace rules.\n',
153
+ dev: 'Usage: yolo tileapp dev <manifest.json> [--port N] [--host H] [--bundle-dir <dir>] [--deny]\n'
154
+ + ' Serve the bundle locally with a mock broker (allow-all; --deny refuses everything).\n',
155
+ install: 'Usage: yolo tileapp install <appId> --workspace <workspaceId> [--accept-optional <perm>]...\n',
156
+ 'add-tile': 'Usage: yolo tileapp add-tile <appId> --workspace <workspaceId> [--name <name>] [--version <v>]\n',
157
+ media: 'Usage: yolo tileapp media push <manifest.json> [--dir <dir>] (uploads store screenshots; additive, never touches the rest of the bundle)\n',
158
+ };
159
+ const TILEAPP_SUBS = ['init', 'validate', 'dev', 'sign', 'publish', 'media', 'install', 'add-tile'];
160
+ const TILEAPP_GROUP_USAGE = [
161
+ 'Usage: yolo tileapp <subcommand> [args] (`yolo tileapp <subcommand> --help` for its options)',
162
+ '',
163
+ ' init <name> Scaffold a personal app.',
164
+ ' validate <manifest> Offline lint: manifest schema + bundle layout.',
165
+ ' dev <manifest> Serve the bundle locally with a mock broker.',
166
+ ' publish <manifest> --personal Register a personal app (no signing or review).',
167
+ ' publish <manifest> Submit a signed manifest for marketplace review.',
168
+ ' sign <manifest> KMS-sign a marketplace manifest.',
169
+ ' media push <manifest> Upload store screenshots.',
170
+ ' install <appId> Install an app into a workspace.',
171
+ ' add-tile <appId> Place an app tile in a workspace.',
172
+ '',
173
+ ].join('\n');
174
+ /** `--help` / `-h` anywhere in a subcommand's args. */
175
+ function wantsHelp(args) {
176
+ return args.some((a) => a === '--help' || a === '-h');
177
+ }
133
178
  function tileAppUsage(sub, message) {
134
179
  process.stderr.write(`yolo tileapp ${sub}: ${message}\n`);
135
- const usage = {
136
- init: 'Usage: yolo tileapp init <name> (scaffolds ./<name>/tileapp.json + index.html)\n',
137
- sign: 'Usage: yolo tileapp sign <manifest.json> --publisher <id> [--key <keyId>] [--stdout]\n',
138
- publish: 'Usage: yolo tileapp publish <manifest.json> --personal [--bundle-dir <dir>] [--context <dir>] [--dockerfile <f>] [--builder auto|podman|skopeo] [--live] (personal app)\n'
139
- + ' or: yolo tileapp publish <manifest.json> [--channel beta|stable] [--image-digest <d>] (marketplace)\n',
140
- validate: 'Usage: yolo tileapp validate <manifest.json> [--bundle-dir <dir>] [--personal]\n',
141
- dev: 'Usage: yolo tileapp dev <manifest.json> [--port N] [--host H] [--bundle-dir <dir>] [--deny]\n',
142
- install: 'Usage: yolo tileapp install <appId> --workspace <workspaceId> [--accept-optional <perm>]...\n',
143
- 'add-tile': 'Usage: yolo tileapp add-tile <appId> --workspace <workspaceId> [--name <name>] [--version <v>]\n',
144
- media: 'Usage: yolo tileapp media push <manifest.json> [--dir <dir>] (uploads store screenshots; additive, never touches the rest of the bundle)\n',
145
- };
146
- process.stderr.write(usage[sub]);
180
+ process.stderr.write(TILEAPP_USAGE[sub]);
147
181
  return 64;
148
182
  }
149
183
  async function runTileAppInstallCmd(args) {
@@ -339,11 +373,18 @@ async function runTileAppPublishCmd(args) {
339
373
  let builder;
340
374
  let personal = false;
341
375
  let live = false;
376
+ const include = [];
342
377
  for (let i = 0; i < args.length; i++) {
343
378
  const a = args[i];
344
379
  if (a === '--personal' || a === '--private') {
345
380
  personal = true;
346
381
  }
382
+ else if (a === '--include') {
383
+ const v = args[++i];
384
+ if (!v || v.startsWith('--'))
385
+ return tileAppUsage('publish', '--include requires a value');
386
+ include.push(v);
387
+ }
347
388
  else if (a === '--live') {
348
389
  live = true;
349
390
  }
@@ -390,7 +431,7 @@ async function runTileAppPublishCmd(args) {
390
431
  // bundle (no signing/review). Distinct from the marketplace publish below.
391
432
  if (personal) {
392
433
  const { runTileAppPublishPersonal, exitCodeForFailure } = await import('./tileapp-personal.js');
393
- const result = await runTileAppPublishPersonal({ manifestPath, bundleDir, context, dockerfile, builder, live });
434
+ const result = await runTileAppPublishPersonal({ manifestPath, bundleDir, include, context, dockerfile, builder, live });
394
435
  if (result.ok) {
395
436
  process.stdout.write(`${result.output}\n`);
396
437
  return 0;
@@ -403,8 +444,8 @@ async function runTileAppPublishCmd(args) {
403
444
  process.stderr.write(`FAIL [${result.kind}]: ${result.message}\n`);
404
445
  return exitCodeForFailure(result.kind);
405
446
  }
406
- if (bundleDir || context || dockerfile || builder || live)
407
- return tileAppUsage('publish', '--bundle-dir/--context/--dockerfile/--builder/--live are only valid with --personal');
447
+ if (bundleDir || include.length > 0 || context || dockerfile || builder || live)
448
+ return tileAppUsage('publish', '--bundle-dir/--include/--context/--dockerfile/--builder/--live are only valid with --personal');
408
449
  const result = await runTileAppPublish({ manifestPath, channel, imageDigest });
409
450
  if (result.ok) {
410
451
  process.stdout.write(`${result.output}\n`);
@@ -473,7 +514,7 @@ async function runTileAppValidateCmd(args) {
473
514
  const { runTileAppValidate, devExitCode } = await import('./tileapp-developer.js');
474
515
  let manifestPath;
475
516
  let bundleDir;
476
- let personal = false;
517
+ let personal;
477
518
  for (let i = 0; i < args.length; i++) {
478
519
  const a = args[i];
479
520
  if (a === '--bundle-dir') {
@@ -482,8 +523,15 @@ async function runTileAppValidateCmd(args) {
482
523
  return tileAppUsage('validate', '--bundle-dir requires a value');
483
524
  }
484
525
  else if (a === '--personal') {
526
+ if (personal === false)
527
+ return tileAppUsage('validate', '--personal and --marketplace are mutually exclusive');
485
528
  personal = true;
486
529
  }
530
+ else if (a === '--marketplace') {
531
+ if (personal === true)
532
+ return tileAppUsage('validate', '--personal and --marketplace are mutually exclusive');
533
+ personal = false;
534
+ }
487
535
  else if (!a.startsWith('-') && !manifestPath)
488
536
  manifestPath = a;
489
537
  else
@@ -742,28 +790,38 @@ async function main(argv) {
742
790
  }
743
791
  if (cmd === 'tileapp') {
744
792
  const sub = args[1];
793
+ const rest = args.slice(2);
794
+ if (sub === '--help' || sub === '-h' || sub === 'help') {
795
+ process.stdout.write(TILEAPP_GROUP_USAGE);
796
+ return 0;
797
+ }
798
+ if (sub && TILEAPP_SUBS.includes(sub) && wantsHelp(rest)) {
799
+ process.stdout.write(TILEAPP_USAGE[sub]);
800
+ return 0;
801
+ }
745
802
  if (sub === 'init')
746
- return runTileAppInitCmd(args.slice(2));
803
+ return runTileAppInitCmd(rest);
747
804
  if (sub === 'sign')
748
- return runTileAppSignCmd(args.slice(2));
805
+ return runTileAppSignCmd(rest);
749
806
  if (sub === 'publish')
750
- return runTileAppPublishCmd(args.slice(2));
807
+ return runTileAppPublishCmd(rest);
751
808
  if (sub === 'validate')
752
- return runTileAppValidateCmd(args.slice(2));
809
+ return runTileAppValidateCmd(rest);
753
810
  if (sub === 'dev')
754
- return runTileAppDevCmd(args.slice(2));
811
+ return runTileAppDevCmd(rest);
755
812
  if (sub === 'install')
756
- return runTileAppInstallCmd(args.slice(2));
813
+ return runTileAppInstallCmd(rest);
757
814
  if (sub === 'add-tile')
758
- return runTileAppAddTileCmd(args.slice(2));
815
+ return runTileAppAddTileCmd(rest);
759
816
  if (sub === 'media')
760
- return runTileAppMediaCmd(args.slice(2));
817
+ return runTileAppMediaCmd(rest);
761
818
  if (!sub) {
762
819
  process.stderr.write('yolo: tileapp requires a subcommand (init, validate, dev, sign, publish, media, install, add-tile)\n');
820
+ process.stderr.write(TILEAPP_GROUP_USAGE);
763
821
  return 64;
764
822
  }
765
823
  process.stderr.write(`yolo: unknown tileapp subcommand '${sub}'\n`);
766
- process.stderr.write('Subcommands: init, validate, dev, sign, publish, media, install, add-tile\n');
824
+ process.stderr.write(TILEAPP_GROUP_USAGE);
767
825
  return 64;
768
826
  }
769
827
  if (cmd === 'git') {
@@ -21,7 +21,7 @@ import * as fs from 'node:fs';
21
21
  import * as path from 'node:path';
22
22
  import * as http from 'node:http';
23
23
  import { createServeHandler } from './serve.js';
24
- import { validateManifest, isRuntimeManifest, isWorkerRuntimeManifest, publishGateErrors } from './tileapp-validator.js';
24
+ import { isRuntimeManifest, isPersonalManifest, lintManifest } from './tileapp-validator.js';
25
25
  /** The mock-broker + helper routes the dev server mounts (under a reserved
26
26
  * prefix so they can't collide with a real bundle asset path). */
27
27
  export const DEV_BROKER_PATH = '/__yolo/broker';
@@ -110,15 +110,9 @@ export function runTileAppValidate(opts) {
110
110
  const read = readManifestFile(opts.manifestPath);
111
111
  if (!read.ok)
112
112
  return { ok: false, kind: 'io', message: read.message };
113
- // A runtime personal app publishes an OCI archive and gets no R2 bundle, so
114
- // only a PURE-UI personal manifest may use the `media/<file>` ref form.
115
- const v = validateManifest(read.manifest, {
116
- allowPlatformHostedScreenshots: !!opts.personal && !isRuntimeManifest(read.manifest),
117
- });
118
- // The image-digest gate is the marketplace publish rule; a PERSONAL worker app
119
- // ships its backend in the bundle and has no image to pin.
120
- const skipGate = !!opts.personal && isWorkerRuntimeManifest(read.manifest);
121
- const errors = [...v.errors, ...(skipGate ? [] : publishGateErrors(read.manifest))];
113
+ const inferred = opts.personal === undefined;
114
+ const personal = opts.personal ?? isPersonalManifest(read.manifest);
115
+ const errors = lintManifest(read.manifest, { personal });
122
116
  // A non-object manifest is fully reported by validateManifest; bail before the
123
117
  // bundle/runtime checks (which deref manifest fields) so we never crash on it.
124
118
  const manifestIsObject = typeof read.manifest === 'object' && read.manifest !== null && !Array.isArray(read.manifest);
@@ -139,13 +133,17 @@ export function runTileAppValidate(opts) {
139
133
  bundleNote = '\n runtime app — surface served from its container image (no local bundle checked)';
140
134
  }
141
135
  if (errors.length > 0) {
142
- return { ok: false, kind: 'validation', message: `manifest invalid (${errors.length} issue${errors.length === 1 ? '' : 's'}):\n - ${errors.join('\n - ')}` };
136
+ const rules = personal ? 'personal-app rules' : 'marketplace rules';
137
+ return { ok: false, kind: 'validation', message: `manifest invalid under the ${rules} (${errors.length} issue${errors.length === 1 ? '' : 's'}):\n - ${errors.join('\n - ')}` };
143
138
  }
144
139
  const id = String(read.manifest.id);
145
140
  const version = String(read.manifest.version);
141
+ const modeNote = personal
142
+ ? `\n rules: personal app${inferred ? ' (no marketplace `publisher`; pass --marketplace for the marketplace rules)' : ''} — publish with: yolo tileapp publish ${opts.manifestPath} --personal`
143
+ : `\n rules: marketplace${inferred ? ` (publisher '${String(read.manifest.publisher)}'; pass --personal for a personal app)` : ''}`;
146
144
  return {
147
145
  ok: true,
148
- output: `OK: ${id}@${version} is valid.${bundleNote}\n note: mcp-scope + secret-key NAMES are confirmed server-side at publish.`,
146
+ output: `OK: ${id}@${version} is valid.${bundleNote}${modeNote}\n note: mcp-scope + secret-key NAMES are confirmed server-side at publish.`,
149
147
  };
150
148
  }
151
149
  /**
@@ -197,7 +195,7 @@ export async function runTileAppDev(opts) {
197
195
  // Block on schema AND publish-gate errors before serving — `dev` claims to
198
196
  // validate before serving, so it must reject anything publish would (e.g. an
199
197
  // image-only manifest missing its pinned digest).
200
- const gateErrors = [...validateManifest(read.manifest).errors, ...publishGateErrors(read.manifest)];
198
+ const gateErrors = lintManifest(read.manifest, { personal: isPersonalManifest(read.manifest) });
201
199
  if (gateErrors.length) {
202
200
  process.stderr.write(`FAIL [validation]: manifest invalid:\n - ${gateErrors.join('\n - ')}\n`);
203
201
  return devExitCode('validation');
@@ -22,7 +22,8 @@ import fs from 'node:fs';
22
22
  import os from 'node:os';
23
23
  import path from 'node:path';
24
24
  import { spawn } from 'node:child_process';
25
- import { podSessionTelemetryHeaders, resolveUserToken } from './auth-context.js';
25
+ import { defaultReadFile, podSessionTelemetryHeaders, resolveUserToken } from './auth-context.js';
26
+ import { isProductionTarget, podProvisionedApiUrl, sameApiOrigin, targetApiUrl } from './api-env.js';
26
27
  import { resolveCommonApiUrl } from './api-url.js';
27
28
  import { formatOwnerApprovalPending, ownerApprovalRequestedOf } from './pod-owner-approval.js';
28
29
  import { missingUserTokenMessage } from './api-env.js';
@@ -129,7 +130,9 @@ export function runTileAppInit(opts) {
129
130
  id: name,
130
131
  version: '1.0.0',
131
132
  displayName: title,
132
- publisher: 'personal',
133
+ // No `publisher`: a personal app omits it and the server stamps
134
+ // `personal:<ownerId>`. `id` is the app's LOCAL name; the server namespaces
135
+ // it to `pa-<ownerId>-<id>` (see isPersonalManifest).
133
136
  description: `${title} — a personal tile-app.`,
134
137
  ui: { icon: '🧩', color: '#4f46e5', label: title },
135
138
  surface: { kind: 'iframe', entry: 'index.html', tilePrefersSize: { rowSpan: 2, colSpan: 2 } },
@@ -190,36 +193,10 @@ body { font: 15px/1.5 system-ui, sans-serif; margin: 0; display: grid; place-ite
190
193
  const status = document.getElementById('status');
191
194
  if (status) status.textContent = 'Ready — edit app.js to build your app.';
192
195
  `;
193
- // Store screenshots live in `media/`. Scaffolding the directory (with a
194
- // README, since an empty dir wouldn't survive and a dotfile is skipped by
195
- // both the collector and the server) is what makes the feature discoverable
196
- // — an author who never learns the folder exists ships a listing with no
197
- // preview and no idea one was possible.
198
- const mediaReadme = `# Store screenshots
199
-
200
- Drop screenshots here, then reference them from tileapp.json:
201
-
202
- "screenshots": ["media/01-main.webp"]
203
-
204
- \`yolo tileapp publish tileapp.json --personal\` walks this directory and
205
- uploads whatever is in it; the platform serves each file at
206
- /v1/tileapps/<appId>/media/<file>.
207
-
208
- format 1280x800 (16:10) webp, <= 400 KB each, 1-6 images, first is the hero
209
- capture render at 2x and downscale — the store card crops to ~320px wide
210
- content show the app doing its job on realistic data; an empty state or a
211
- permission prompt is a wasted slot
212
- budget bundles cap at 100 files / 3 MB total
213
-
214
- An absolute https:// URL works too, and is the ONLY option for a runtime app
215
- (it publishes an image, not a bundle, so it has nowhere to put these).
216
-
217
- Upload (additive — leaves the rest of your bundle alone):
218
-
219
- yolo tileapp media push tileapp.json
220
-
221
- Check refs before publishing: yolo tileapp validate tileapp.json --personal
222
- `;
196
+ // Store screenshots live in `media/`. The directory is created EMPTY: a
197
+ // README there would be uploaded with the bundle and served publicly (and
198
+ // `publish` now skips README/*.md files anyway). The guidance is in the
199
+ // output below instead.
223
200
  try {
224
201
  fs.mkdirSync(dir, { recursive: false });
225
202
  fs.writeFileSync(path.join(dir, 'tileapp.json'), `${JSON.stringify(manifest, null, 2)}\n`);
@@ -227,14 +204,13 @@ Check refs before publishing: yolo tileapp validate tileapp.json --personal
227
204
  fs.writeFileSync(path.join(dir, 'app.js'), appJs);
228
205
  fs.writeFileSync(path.join(dir, 'style.css'), styleCss);
229
206
  fs.mkdirSync(path.join(dir, 'media'), { recursive: false });
230
- fs.writeFileSync(path.join(dir, 'media', 'README.md'), mediaReadme);
231
207
  }
232
208
  catch (e) {
233
209
  return { ok: false, kind: 'io', message: `scaffold failed: ${e.message}` };
234
210
  }
235
211
  return {
236
212
  ok: true,
237
- output: `Created ${name}/ (tileapp.json + index.html + app.js + style.css + media/)\n note: bundle CSP is \`script-src 'self'\` — keep JS in app.js (no inline <script>, no eval, no network); CSS goes in style.css\n note: drop a 1280x800 webp in media/ and add \`"screenshots": ["media/01-main.webp"]\` to get a store preview (see media/README.md)\n next: cd ${name} && yolo tileapp publish tileapp.json --personal`,
213
+ output: `Created ${name}/ (tileapp.json + index.html + app.js + style.css + media/)\n note: bundle CSP is \`script-src 'self'\` — keep JS in app.js (no inline <script>, no eval, no network); CSS goes in style.css\n note: store preview: drop a 1280x800 (16:10) webp, <= 400 KB, in media/ and add \`"screenshots": ["media/01-main.webp"]\` (1-6 images, the first is the hero; \`yolo tileapp media push tileapp.json\` uploads them without a full publish)\n note: tileapp.json has no \`publisher\` on purpose: the server stamps it; \`id\` is your app's local name\n next: cd ${name} && yolo tileapp publish tileapp.json --personal`,
238
214
  };
239
215
  }
240
216
  /**
@@ -305,7 +281,7 @@ export async function runTileAppMediaPush(opts) {
305
281
  entries = fs.readdirSync(dir);
306
282
  }
307
283
  catch {
308
- return { ok: false, kind: 'io', message: `no media directory at ${dir} — create it and add your screenshots (see media/README.md from \`yolo tileapp init\`)` };
284
+ return { ok: false, kind: 'io', message: `no media directory at ${dir} — create it and add your screenshots (1280x800 webp, referenced as \"screenshots\": [\"media/<file>\"])` };
309
285
  }
310
286
  const files = [];
311
287
  for (const name of entries.sort()) {
@@ -421,18 +397,53 @@ export async function runTileAppMediaPush(opts) {
421
397
  + `Keep ${opts.manifestPath} in sync by adding the same array, so your next publish doesn't drop them.`,
422
398
  };
423
399
  }
424
- /** Recursively collect a bundle dir's files as upload entries. Skips VCS/dep
425
- * dirs and the manifest itself; classifies text vs binary by extension. */
426
- function collectBundleFiles(rootDir, manifestPath) {
400
+ /**
401
+ * Documentation files the bundle does NOT upload by default: `README*` (any
402
+ * extension, any case) and `*.md` / `*.markdown`, at any depth. A bundle is
403
+ * served PUBLICLY at the app's origin, and these are almost always notes for
404
+ * the author (e.g. the old `init`'s media/README.md), not app content.
405
+ */
406
+ export function isBundleDocFile(relPath) {
407
+ const base = relPath.slice(relPath.lastIndexOf('/') + 1).toLowerCase();
408
+ return /^readme(\..*)?$/.test(base) || base.endsWith('.md') || base.endsWith('.markdown');
409
+ }
410
+ /**
411
+ * Recursively collect a bundle dir's files as upload entries.
412
+ *
413
+ * What is NOT uploaded (the bundle is public):
414
+ * - dotfiles / dot-directories, and the `node_modules`, VCS and `.yolo` dirs
415
+ * - the manifest itself
416
+ * - documentation files (`isBundleDocFile`), UNLESS the file is
417
+ * · `surface.entry`, or
418
+ * · named in `include` (`--include <path>`, relative to the bundle dir), or
419
+ * · referenced from an uploaded text file (html/js/css/json/svg/…) by its
420
+ * bundle path or its file name — the app fetches or links it.
421
+ * Skipped doc files are returned in `skipped` so publish can say so.
422
+ */
423
+ export function collectBundleFiles(rootDir, manifestPath, opts = {}) {
427
424
  const out = [];
425
+ const docs = [];
428
426
  const manifestAbs = path.resolve(manifestPath);
429
427
  const root = path.resolve(rootDir);
430
428
  let total = 0;
431
429
  const SKIP_DIRS = new Set(['node_modules', '.git', '.yolo']);
430
+ const add = (rel, buf) => {
431
+ total += buf.byteLength;
432
+ if (out.length + 1 > MAX_FILES)
433
+ return `too many files (max ${MAX_FILES})`;
434
+ if (total > MAX_TOTAL_BYTES)
435
+ return `bundle exceeds ${MAX_TOTAL_BYTES} bytes — use a smaller bundle`;
436
+ const ext = path.extname(rel).toLowerCase();
437
+ if (TEXT_EXTS.has(ext))
438
+ out.push({ path: rel, content: buf.toString('utf8'), encoding: 'utf8' });
439
+ else
440
+ out.push({ path: rel, content: buf.toString('base64'), encoding: 'base64' });
441
+ return null;
442
+ };
432
443
  const walk = (abs) => {
433
444
  for (const entry of fs.readdirSync(abs, { withFileTypes: true })) {
434
445
  // Skip dotfiles/dotdirs entirely — the bundle is served PUBLICLY, so a
435
- // stray .env/.npmrc/.git from the project dir must never be uploaded (the
446
+ // stray .env/.npmrc from the project dir must never be uploaded (the
436
447
  // server's sanitizeBundlePath also rejects dot-leading paths). codex Round-3 P1.
437
448
  if (entry.name.startsWith('.'))
438
449
  continue;
@@ -450,17 +461,13 @@ function collectBundleFiles(rootDir, manifestPath) {
450
461
  if (path.resolve(childAbs) === manifestAbs)
451
462
  continue; // never upload the manifest
452
463
  const rel = path.relative(root, childAbs).split(path.sep).join('/');
453
- const buf = fs.readFileSync(childAbs);
454
- total += buf.byteLength;
455
- if (out.length + 1 > MAX_FILES)
456
- return `too many files (max ${MAX_FILES})`;
457
- if (total > MAX_TOTAL_BYTES)
458
- return `bundle exceeds ${MAX_TOTAL_BYTES} bytes — use a smaller bundle`;
459
- const ext = path.extname(rel).toLowerCase();
460
- if (TEXT_EXTS.has(ext))
461
- out.push({ path: rel, content: buf.toString('utf8'), encoding: 'utf8' });
462
- else
463
- out.push({ path: rel, content: buf.toString('base64'), encoding: 'base64' });
464
+ if (isBundleDocFile(rel)) {
465
+ docs.push({ rel, abs: childAbs });
466
+ continue;
467
+ } // decided below
468
+ const err = add(rel, fs.readFileSync(childAbs));
469
+ if (err)
470
+ return err;
464
471
  }
465
472
  return null;
466
473
  };
@@ -472,9 +479,39 @@ function collectBundleFiles(rootDir, manifestPath) {
472
479
  catch (e) {
473
480
  return { ok: false, message: `reading bundle failed: ${e.message}` };
474
481
  }
482
+ const norm = (p) => p.split('\\').join('/').replace(/^(\.\/)+/, '').replace(/^\/+/, '');
483
+ const include = new Set((opts.include ?? []).map(norm));
484
+ const docPaths = new Set(docs.map((d) => d.rel));
485
+ for (const inc of include) {
486
+ if (!docPaths.has(inc) && !out.some((f) => f.path === inc)) {
487
+ return { ok: false, message: `--include ${inc}: no such file in the bundle dir ${rootDir} (dotfiles are never uploaded)` };
488
+ }
489
+ }
490
+ const entry = norm(opts.entry || 'index.html');
491
+ const texts = out.filter((f) => f.encoding === 'utf8').map((f) => f.content);
492
+ const referenced = (rel) => {
493
+ const base = rel.slice(rel.lastIndexOf('/') + 1);
494
+ return texts.some((t) => t.includes(rel) || t.includes(base));
495
+ };
496
+ const skipped = [];
497
+ for (const d of docs.sort((x, y) => (x.rel < y.rel ? -1 : x.rel > y.rel ? 1 : 0))) {
498
+ if (d.rel === entry || include.has(d.rel) || referenced(d.rel)) {
499
+ try {
500
+ const err = add(d.rel, fs.readFileSync(d.abs));
501
+ if (err)
502
+ return { ok: false, message: err };
503
+ }
504
+ catch (e) {
505
+ return { ok: false, message: `reading bundle failed: ${e.message}` };
506
+ }
507
+ }
508
+ else {
509
+ skipped.push(d.rel);
510
+ }
511
+ }
475
512
  if (out.length === 0)
476
513
  return { ok: false, message: `no files found in bundle dir: ${rootDir}` };
477
- return { ok: true, files: out, totalBytes: total };
514
+ return { ok: true, files: out, totalBytes: total, skipped };
478
515
  }
479
516
  export async function runTileAppPublishPersonal(opts) {
480
517
  const env = opts.env ?? process.env;
@@ -513,7 +550,7 @@ export async function runTileAppPublishPersonal(opts) {
513
550
  // Pure-UI path: strict schema lint (the server re-validates authoritatively).
514
551
  // This IS the path that gets an R2 bundle, so the `media/<file>` screenshot
515
552
  // form is available to it — see ScreenshotRefOptions.
516
- const v = validateManifest(read.manifest, { allowPlatformHostedScreenshots: true });
553
+ const v = validateManifest(read.manifest, { personal: true, allowPlatformHostedScreenshots: true });
517
554
  if (v.errors.length > 0) {
518
555
  return { ok: false, kind: 'validation', message: `manifest invalid:\n - ${v.errors.join('\n - ')}` };
519
556
  }
@@ -522,7 +559,10 @@ export async function runTileAppPublishPersonal(opts) {
522
559
  const resolved = resolveBundleDir(opts.manifestPath, read.manifest, opts.bundleDir);
523
560
  if (!resolved.ok)
524
561
  return { ok: false, kind: 'io', message: `bundle: ${resolved.message}` };
525
- const collected = collectBundleFiles(resolved.dir, opts.manifestPath);
562
+ const collected = collectBundleFiles(resolved.dir, opts.manifestPath, {
563
+ entry: read.manifest.surface?.entry,
564
+ include: opts.include,
565
+ });
526
566
  if (!collected.ok)
527
567
  return { ok: false, kind: 'io', message: collected.message };
528
568
  // The server refuses a worker bundle without its backend (INVALID_WORKER_BUNDLE)
@@ -554,6 +594,8 @@ export async function runTileAppPublishPersonal(opts) {
554
594
  // go in ONE request, so the owner approves the publish once. Falls back to the
555
595
  // two-step path below on a server that predates the batch route.
556
596
  let uploadJson = {};
597
+ let installReport;
598
+ const workspaceId = workspaceIdOf(env);
557
599
  let appId = '';
558
600
  let batched = false;
559
601
  if (inWorkspacePod(env)) {
@@ -561,7 +603,13 @@ export async function runTileAppPublishPersonal(opts) {
561
603
  const res = await fetchImpl(`${base}/tileapps/personal/publish-batch`, {
562
604
  method: 'POST',
563
605
  headers,
564
- body: JSON.stringify({ id: localId, manifest: read.manifest, files: collected.files, ...(opts.live ? { live: true } : {}) }),
606
+ // `workspaceId`: this pod's workspace, so the server can move an existing
607
+ // install there to the new version (the install route's own checks apply).
608
+ body: JSON.stringify({
609
+ id: localId, manifest: read.manifest, files: collected.files,
610
+ ...(opts.live ? { live: true } : {}),
611
+ ...(workspaceId ? { workspaceId } : {}),
612
+ }),
565
613
  });
566
614
  const staged = await stagedForOwner(res, `publishing personal app '${localId}'`);
567
615
  if (staged)
@@ -585,6 +633,7 @@ export async function runTileAppPublishPersonal(opts) {
585
633
  return { ok: false, kind: 'http', message: 'publish response missing appId' };
586
634
  appId = json.appId;
587
635
  uploadJson = json.bundle ?? {};
636
+ installReport = json.install;
588
637
  batched = true;
589
638
  }
590
639
  }
@@ -639,10 +688,11 @@ export async function runTileAppPublishPersonal(opts) {
639
688
  return { ok: false, kind: 'http', message: `bundle upload request failed: ${e.message}` };
640
689
  }
641
690
  }
642
- const summary = `Published ${appId} (${collected.files.length} file${collected.files.length === 1 ? '' : 's'}, ${collected.totalBytes} bytes)`;
643
- const next = ' next: install it + add a tile from the workspace (or via the studio.install_app / studio.create_app_tile MCP tools).';
691
+ const summary = `Published ${appId} (${collected.files.length} file${collected.files.length === 1 ? '' : 's'}, ${collected.totalBytes} bytes)`
692
+ + (collected.skipped.length > 0 ? `\n skipped (docs are not uploaded; --include <path> to upload one): ${collected.skipped.join(', ')}` : '');
693
+ const next = installNextLines(appId, workspaceId, installReport);
644
694
  if (!isWorker)
645
- return { ok: true, output: `${summary}\n${next}` };
695
+ return { ok: true, output: [summary, ...next].join('\n') };
646
696
  // A worker app's bundle is stored either way; `publish` says whether its
647
697
  // backend made it, and `live` whether that backend runs on Dynamic Workers.
648
698
  // A version with no backend serves a UI whose /api/* is dead, so it is a failure.
@@ -664,12 +714,55 @@ export async function runTileAppPublishPersonal(opts) {
664
714
  else {
665
715
  lines.push(' backend: no worker placement report — the worker placement may be off on this deployment, so the backend was not published.');
666
716
  }
667
- lines.push(next);
717
+ lines.push(...next);
668
718
  return { ok: true, output: lines.join('\n') };
669
719
  }
670
720
  /** The refusal code (HTTP 409) for a live worker tile when Dynamic Workers is off on the deployment. */
671
721
  const DYNAMIC_WORKERS_DISABLED = 'dynamic-workers-disabled';
672
722
  export const DYNAMIC_WORKERS_DISABLED_MESSAGE = 'live worker tiles are not enabled on this deployment; publish without --live';
723
+ /**
724
+ * This pod's workspace id (`WORKSPACE_ID`, set in every session pod), or
725
+ * undefined. Only when the API is the one the pod belongs to (production, or the
726
+ * API the pod was provisioned for): `$WORKSPACE_ID` names a workspace there,
727
+ * not on another API — the same rule `yolo deploy` follows.
728
+ */
729
+ export function workspaceIdOf(env, readFileImpl = defaultReadFile) {
730
+ const ws = (env.WORKSPACE_ID ?? '').trim().toLowerCase();
731
+ if (!inWorkspacePod(env) || !/^[a-f0-9]{24}$/.test(ws))
732
+ return undefined;
733
+ if (isProductionTarget(env))
734
+ return ws;
735
+ const provisioned = podProvisionedApiUrl(env, readFileImpl);
736
+ return provisioned && sameApiOrigin(provisioned, targetApiUrl(env)) ? ws : undefined;
737
+ }
738
+ /**
739
+ * The publish output's install line(s): what happened to the workspace install,
740
+ * and exactly ONE next command when one is needed.
741
+ */
742
+ export function installNextLines(appId, workspaceId, report) {
743
+ const ws = workspaceId ?? '<workspaceId>';
744
+ const install = `yolo tileapp install ${appId} --workspace ${ws}`;
745
+ const addTile = `yolo tileapp add-tile ${appId} --workspace ${ws}`;
746
+ switch (report?.status) {
747
+ case 'upgraded': {
748
+ const n = report.refreshedTileIds?.length ?? 0;
749
+ return [` install: this workspace's install moved to ${report.version ?? 'the new version'}${n > 0 ? ` (${n} open tile${n === 1 ? '' : 's'} reloading)` : ''} — nothing else to run.`];
750
+ }
751
+ case 'current':
752
+ return [' install: this workspace already runs this version — nothing else to run.'];
753
+ case 'not-installed':
754
+ return [` next: ${install} && ${addTile}`];
755
+ case 'reconsent-required': {
756
+ const perms = [...(report.newRequiredPermissions ?? []), ...(report.stalePermissions ?? []).map((p) => `-${p}`)];
757
+ return [` next: ${install} (this version changes the app's permissions${perms.length ? `: ${perms.join(', ')}` : ''}, so it needs your consent again)`];
758
+ }
759
+ case 'failed':
760
+ return [` install: not moved to the new version (${report.error ?? 'the install step failed'})`, ` next: ${install}`];
761
+ default:
762
+ // No report: published outside a workspace pod, or a server that predates it.
763
+ return [` next: if it's already installed, ${install} moves the install to this version; if not, also run ${addTile}`];
764
+ }
765
+ }
673
766
  /**
674
767
  * Build the app image in-pod with podman, `save` it to an OCI archive in the
675
768
  * workspace, and hand it to common-api's MEDIATED push endpoint — common-api
@@ -805,7 +898,7 @@ async function publishRuntime(p) {
805
898
  return { ok: false, kind: 'http', message: 'publish-image response missing appId' };
806
899
  return {
807
900
  ok: true,
808
- output: `Published runtime app ${json.appId}\n image: ${json.ref}:${json.tag}@${json.digest}\n next: install it + add a tile (studio.install_app / studio.create_app_tile).`,
901
+ output: [`Published runtime app ${json.appId}`, ` image: ${json.ref}:${json.tag}@${json.digest}`, ...installNextLines(json.appId, workspaceIdOf(p.env), undefined)].join('\n'),
809
902
  };
810
903
  }
811
904
  catch (e) {
@@ -15,6 +15,8 @@
15
15
  * confirmed authoritatively at publish — `validate` says so in its output.
16
16
  */
17
17
  const ID_RE = /^[a-z0-9][a-z0-9-]{1,63}$/;
18
+ /** A personal app's local slug (`PERSONAL_LOCAL_ID_RE` server-side). */
19
+ const PERSONAL_LOCAL_ID_RE = /^[a-z0-9][a-z0-9-]{1,31}$/;
18
20
  // ── Store screenshots ───────────────────────────────────────────────────────
19
21
  // Mirror of `common-api/src/types/tileapp-screenshots.ts`. The rules a
20
22
  // publisher needs BEFORE uploading (count, ref form, extension) are checked
@@ -155,13 +157,20 @@ export function validateManifest(raw, opts = {}) {
155
157
  const errors = [];
156
158
  if (!isObj(raw))
157
159
  return { ok: false, errors: ['manifest is not an object'] };
158
- if (!isStr(raw.id) || !ID_RE.test(raw.id))
160
+ if (opts.personal) {
161
+ // The local slug: the server namespaces it to `pa-<ownerId>-<id>` (the CLI
162
+ // reads it from the manifest; `studio.create_personal_app` takes it as its `id` argument).
163
+ if (!isStr(raw.id) || !PERSONAL_LOCAL_ID_RE.test(raw.id))
164
+ errors.push('id must be a lowercase kebab-case slug, 2-32 chars (the app\'s local name; the server namespaces it)');
165
+ }
166
+ else if (!isStr(raw.id) || !ID_RE.test(raw.id))
159
167
  errors.push('id must be a lowercase kebab-case slug (2-64 chars)');
160
168
  if (!isStr(raw.version) || !SEMVER_RE.test(raw.version))
161
169
  errors.push('version must be semver (e.g. 1.0.0)');
162
170
  if (!isStr(raw.displayName))
163
171
  errors.push('displayName is required');
164
- if (!isStr(raw.publisher))
172
+ // Personal: optional and ignored — the server always stamps `personal:<ownerId>`.
173
+ if (!opts.personal && !isStr(raw.publisher))
165
174
  errors.push('publisher is required');
166
175
  if (!isStr(raw.description))
167
176
  errors.push('description is required');
@@ -188,7 +197,9 @@ export function validateManifest(raw, opts = {}) {
188
197
  errors.push('runtime must be an object when present');
189
198
  }
190
199
  else {
191
- if (typeof raw.runtime.port !== 'number' || raw.runtime.port <= 0)
200
+ // A worker (Cloudflare edge backend) listens on no port: `port` is optional
201
+ // there and ignored if given. Process/container runtimes still need it.
202
+ if (raw.runtime.kind !== 'worker' && (typeof raw.runtime.port !== 'number' || raw.runtime.port <= 0))
192
203
  errors.push('runtime.port must be a positive number');
193
204
  if (raw.runtime.exec !== undefined && !isStr(raw.runtime.exec))
194
205
  errors.push('runtime.exec must be a non-empty string when present');
@@ -316,6 +327,40 @@ export function publishGateErrors(manifest) {
316
327
  }
317
328
  return errors;
318
329
  }
330
+ /** The schema error a runtime manifest without `image`/`runtime.exec` gets (the personal publish fills `image`). */
331
+ export const RUNTIME_NEEDS_IMAGE_PREFIX = 'runtime requires either `image`';
332
+ /**
333
+ * Whether a manifest is linted as a PERSONAL app when no `--personal` /
334
+ * `--marketplace` flag says otherwise. The rule (one rule for init, validate,
335
+ * publish and `studio.create_personal_app`): a personal app OMITS `publisher`
336
+ * (the server stamps `personal:<ownerId>`); `"personal"` or `"personal:<id>"`
337
+ * also mean personal. Any other publisher is a marketplace publisher id, linted
338
+ * with the marketplace rules.
339
+ */
340
+ export function isPersonalManifest(manifest) {
341
+ if (!isObj(manifest))
342
+ return false;
343
+ const p = manifest.publisher;
344
+ if (p === undefined || p === null || p === '')
345
+ return true;
346
+ return typeof p === 'string' && (p === 'personal' || p.startsWith('personal:'));
347
+ }
348
+ /**
349
+ * Every lint error for `manifest` under the personal or the marketplace rules —
350
+ * what `validate` and `dev` report. Personal mirrors `publish --personal`: no
351
+ * `publisher`, a local-slug `id`, `media/<file>` screenshots for a bundle app,
352
+ * and no signed-image digest gate (a worker ships its backend in the bundle; a
353
+ * runtime app's `image` is filled server-side from the pushed digest).
354
+ * Marketplace adds the publish gate (`publishGateErrors`).
355
+ */
356
+ export function lintManifest(manifest, opts) {
357
+ if (!opts.personal)
358
+ return [...validateManifest(manifest).errors, ...publishGateErrors(manifest)];
359
+ const runtime = isRuntimeManifest(manifest);
360
+ const subject = runtime && isObj(manifest) ? (({ image: _image, ...rest }) => rest)(manifest) : manifest;
361
+ const errors = validateManifest(subject, { personal: true, allowPlatformHostedScreenshots: !runtime }).errors;
362
+ return runtime ? errors.filter((e) => !e.startsWith(RUNTIME_NEEDS_IMAGE_PREFIX)) : errors;
363
+ }
319
364
  /**
320
365
  * True for a `runtime.kind: 'worker'` manifest: a Cloudflare edge tile whose
321
366
  * backend ships IN the bundle under `_worker/` — no image, no podman build.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@yolo-labs/yolo-cli",
3
- "version": "1.1.0",
3
+ "version": "1.2.0",
4
4
  "description": "YOLO Studio CLI for workspace context, artifacts, personal apps and hosting.",
5
5
  "license": "MIT",
6
6
  "repository": {