@yolo-labs/yolo-cli 1.1.0 → 1.3.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.',
@@ -90,8 +92,10 @@ function printHelp() {
90
92
  ' bundle. Runtime (manifest has `runtime`): builds the image in-pod',
91
93
  ' + mediated-push to your registry namespace. Worker (`runtime.kind:',
92
94
  " 'worker'`): uploads the bundle incl. its _worker/ backend, no build.",
93
- ' [--live] Worker: run the backend live on Dynamic Workers (owner only, in-progress).',
95
+ ' [--live] An in-progress edit, owner only: a worker app\'s backend runs on Dynamic Workers;',
96
+ ' an interface-only app is shown only on your own tile (customers keep the published version).',
94
97
  ' [--bundle-dir <dir>] Pure-UI: override the static-bundle directory to upload.',
98
+ ' [--include <path>] Upload a README*/*.md file that is skipped by default (repeatable).',
95
99
  ' [--context <dir>] [--dockerfile <f>] Runtime: build context + Dockerfile (default: the manifest dir).',
96
100
  ' [--builder auto|podman|skopeo] Runtime build engine. auto (default): skopeo assembler for RUN-less',
97
101
  ' Dockerfiles (no container engine — works in-pod), else podman.',
@@ -130,20 +134,51 @@ function printHelp() {
130
134
  '',
131
135
  ].join('\n'));
132
136
  }
137
+ /** One usage block per `yolo tileapp` subcommand: printed to stdout for `--help`, to stderr on a usage error. */
138
+ const TILEAPP_USAGE = {
139
+ init: 'Usage: yolo tileapp init <name>\n'
140
+ + ' Scaffold a personal app: ./<name>/tileapp.json + index.html + app.js + style.css.\n'
141
+ + ' The manifest has `id` (the app\'s local name) and no `publisher`: the server stamps it.\n',
142
+ sign: 'Usage: yolo tileapp sign <manifest.json> --publisher <id> [--key <keyId>] [--stdout]\n'
143
+ + ' KMS-sign a marketplace manifest (POST /v1/publisher/sign).\n',
144
+ 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'
145
+ + ' or: yolo tileapp publish <manifest.json> [--channel beta|stable] [--image-digest <d>] (marketplace)\n'
146
+ + ' Bundle files: dotfiles, node_modules/, README* and *.md / *.markdown files are NOT uploaded (the\n'
147
+ + ' bundle is served publicly) unless the file is surface.entry, is referenced by another uploaded\n'
148
+ + ' file, or is named with --include <path> (repeatable, relative to the bundle dir).\n'
149
+ + ' If the app is installed in this workspace, a new version moves that install to it\n'
150
+ + ' (when it asks for no new permissions); otherwise the output names the one command to run.\n',
151
+ validate: 'Usage: yolo tileapp validate <manifest.json> [--bundle-dir <dir>] [--personal | --marketplace]\n'
152
+ + ' Offline lint (no auth). Without a flag, a manifest with no `publisher` (or "personal") is\n'
153
+ + ' checked with the personal-app rules, any other publisher with the marketplace rules.\n',
154
+ dev: 'Usage: yolo tileapp dev <manifest.json> [--port N] [--host H] [--bundle-dir <dir>] [--deny]\n'
155
+ + ' Serve the bundle locally with a mock broker (allow-all; --deny refuses everything).\n',
156
+ install: 'Usage: yolo tileapp install <appId> --workspace <workspaceId> [--accept-optional <perm>]...\n',
157
+ 'add-tile': 'Usage: yolo tileapp add-tile <appId> --workspace <workspaceId> [--name <name>] [--version <v>]\n',
158
+ media: 'Usage: yolo tileapp media push <manifest.json> [--dir <dir>] (uploads store screenshots; additive, never touches the rest of the bundle)\n',
159
+ };
160
+ const TILEAPP_SUBS = ['init', 'validate', 'dev', 'sign', 'publish', 'media', 'install', 'add-tile'];
161
+ const TILEAPP_GROUP_USAGE = [
162
+ 'Usage: yolo tileapp <subcommand> [args] (`yolo tileapp <subcommand> --help` for its options)',
163
+ '',
164
+ ' init <name> Scaffold a personal app.',
165
+ ' validate <manifest> Offline lint: manifest schema + bundle layout.',
166
+ ' dev <manifest> Serve the bundle locally with a mock broker.',
167
+ ' publish <manifest> --personal Register a personal app (no signing or review).',
168
+ ' publish <manifest> Submit a signed manifest for marketplace review.',
169
+ ' sign <manifest> KMS-sign a marketplace manifest.',
170
+ ' media push <manifest> Upload store screenshots.',
171
+ ' install <appId> Install an app into a workspace.',
172
+ ' add-tile <appId> Place an app tile in a workspace.',
173
+ '',
174
+ ].join('\n');
175
+ /** `--help` / `-h` anywhere in a subcommand's args. */
176
+ function wantsHelp(args) {
177
+ return args.some((a) => a === '--help' || a === '-h');
178
+ }
133
179
  function tileAppUsage(sub, message) {
134
180
  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]);
181
+ process.stderr.write(TILEAPP_USAGE[sub]);
147
182
  return 64;
148
183
  }
149
184
  async function runTileAppInstallCmd(args) {
@@ -339,11 +374,18 @@ async function runTileAppPublishCmd(args) {
339
374
  let builder;
340
375
  let personal = false;
341
376
  let live = false;
377
+ const include = [];
342
378
  for (let i = 0; i < args.length; i++) {
343
379
  const a = args[i];
344
380
  if (a === '--personal' || a === '--private') {
345
381
  personal = true;
346
382
  }
383
+ else if (a === '--include') {
384
+ const v = args[++i];
385
+ if (!v || v.startsWith('--'))
386
+ return tileAppUsage('publish', '--include requires a value');
387
+ include.push(v);
388
+ }
347
389
  else if (a === '--live') {
348
390
  live = true;
349
391
  }
@@ -390,7 +432,7 @@ async function runTileAppPublishCmd(args) {
390
432
  // bundle (no signing/review). Distinct from the marketplace publish below.
391
433
  if (personal) {
392
434
  const { runTileAppPublishPersonal, exitCodeForFailure } = await import('./tileapp-personal.js');
393
- const result = await runTileAppPublishPersonal({ manifestPath, bundleDir, context, dockerfile, builder, live });
435
+ const result = await runTileAppPublishPersonal({ manifestPath, bundleDir, include, context, dockerfile, builder, live });
394
436
  if (result.ok) {
395
437
  process.stdout.write(`${result.output}\n`);
396
438
  return 0;
@@ -403,8 +445,8 @@ async function runTileAppPublishCmd(args) {
403
445
  process.stderr.write(`FAIL [${result.kind}]: ${result.message}\n`);
404
446
  return exitCodeForFailure(result.kind);
405
447
  }
406
- if (bundleDir || context || dockerfile || builder || live)
407
- return tileAppUsage('publish', '--bundle-dir/--context/--dockerfile/--builder/--live are only valid with --personal');
448
+ if (bundleDir || include.length > 0 || context || dockerfile || builder || live)
449
+ return tileAppUsage('publish', '--bundle-dir/--include/--context/--dockerfile/--builder/--live are only valid with --personal');
408
450
  const result = await runTileAppPublish({ manifestPath, channel, imageDigest });
409
451
  if (result.ok) {
410
452
  process.stdout.write(`${result.output}\n`);
@@ -473,7 +515,7 @@ async function runTileAppValidateCmd(args) {
473
515
  const { runTileAppValidate, devExitCode } = await import('./tileapp-developer.js');
474
516
  let manifestPath;
475
517
  let bundleDir;
476
- let personal = false;
518
+ let personal;
477
519
  for (let i = 0; i < args.length; i++) {
478
520
  const a = args[i];
479
521
  if (a === '--bundle-dir') {
@@ -482,8 +524,15 @@ async function runTileAppValidateCmd(args) {
482
524
  return tileAppUsage('validate', '--bundle-dir requires a value');
483
525
  }
484
526
  else if (a === '--personal') {
527
+ if (personal === false)
528
+ return tileAppUsage('validate', '--personal and --marketplace are mutually exclusive');
485
529
  personal = true;
486
530
  }
531
+ else if (a === '--marketplace') {
532
+ if (personal === true)
533
+ return tileAppUsage('validate', '--personal and --marketplace are mutually exclusive');
534
+ personal = false;
535
+ }
487
536
  else if (!a.startsWith('-') && !manifestPath)
488
537
  manifestPath = a;
489
538
  else
@@ -742,28 +791,38 @@ async function main(argv) {
742
791
  }
743
792
  if (cmd === 'tileapp') {
744
793
  const sub = args[1];
794
+ const rest = args.slice(2);
795
+ if (sub === '--help' || sub === '-h' || sub === 'help') {
796
+ process.stdout.write(TILEAPP_GROUP_USAGE);
797
+ return 0;
798
+ }
799
+ if (sub && TILEAPP_SUBS.includes(sub) && wantsHelp(rest)) {
800
+ process.stdout.write(TILEAPP_USAGE[sub]);
801
+ return 0;
802
+ }
745
803
  if (sub === 'init')
746
- return runTileAppInitCmd(args.slice(2));
804
+ return runTileAppInitCmd(rest);
747
805
  if (sub === 'sign')
748
- return runTileAppSignCmd(args.slice(2));
806
+ return runTileAppSignCmd(rest);
749
807
  if (sub === 'publish')
750
- return runTileAppPublishCmd(args.slice(2));
808
+ return runTileAppPublishCmd(rest);
751
809
  if (sub === 'validate')
752
- return runTileAppValidateCmd(args.slice(2));
810
+ return runTileAppValidateCmd(rest);
753
811
  if (sub === 'dev')
754
- return runTileAppDevCmd(args.slice(2));
812
+ return runTileAppDevCmd(rest);
755
813
  if (sub === 'install')
756
- return runTileAppInstallCmd(args.slice(2));
814
+ return runTileAppInstallCmd(rest);
757
815
  if (sub === 'add-tile')
758
- return runTileAppAddTileCmd(args.slice(2));
816
+ return runTileAppAddTileCmd(rest);
759
817
  if (sub === 'media')
760
- return runTileAppMediaCmd(args.slice(2));
818
+ return runTileAppMediaCmd(rest);
761
819
  if (!sub) {
762
820
  process.stderr.write('yolo: tileapp requires a subcommand (init, validate, dev, sign, publish, media, install, add-tile)\n');
821
+ process.stderr.write(TILEAPP_GROUP_USAGE);
763
822
  return 64;
764
823
  }
765
824
  process.stderr.write(`yolo: unknown tileapp subcommand '${sub}'\n`);
766
- process.stderr.write('Subcommands: init, validate, dev, sign, publish, media, install, add-tile\n');
825
+ process.stderr.write(TILEAPP_GROUP_USAGE);
767
826
  return 64;
768
827
  }
769
828
  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;
@@ -495,8 +532,10 @@ export async function runTileAppPublishPersonal(opts) {
495
532
  return { ok: false, kind: 'validation', message: `manifest "id" must be a lowercase kebab-case slug, 2-32 chars (got '${localId}')` };
496
533
  }
497
534
  const isWorker = isWorkerRuntimeManifest(read.manifest);
498
- if (opts.live && !isWorker) {
499
- return { ok: false, kind: 'usage', message: "--live applies only to a runtime.kind 'worker' app (its backend is what runs live); publish without --live" };
535
+ // --live on an image/container runtime app has nothing to run live; on a pure-UI app it is a
536
+ // static live edit (an owner-only preview), on a worker app its backend runs on Dynamic Workers.
537
+ if (opts.live && isRuntimeManifest(read.manifest)) {
538
+ return { ok: false, kind: 'usage', message: "--live applies to an interface-only or runtime.kind 'worker' app; publish without --live" };
500
539
  }
501
540
  // Runtime app (has `runtime`/`image`): build the image in-pod + mediated push.
502
541
  // A worker app is NOT one (isRuntimeManifest excludes it): it falls through to
@@ -513,7 +552,7 @@ export async function runTileAppPublishPersonal(opts) {
513
552
  // Pure-UI path: strict schema lint (the server re-validates authoritatively).
514
553
  // This IS the path that gets an R2 bundle, so the `media/<file>` screenshot
515
554
  // form is available to it — see ScreenshotRefOptions.
516
- const v = validateManifest(read.manifest, { allowPlatformHostedScreenshots: true });
555
+ const v = validateManifest(read.manifest, { personal: true, allowPlatformHostedScreenshots: true });
517
556
  if (v.errors.length > 0) {
518
557
  return { ok: false, kind: 'validation', message: `manifest invalid:\n - ${v.errors.join('\n - ')}` };
519
558
  }
@@ -522,7 +561,10 @@ export async function runTileAppPublishPersonal(opts) {
522
561
  const resolved = resolveBundleDir(opts.manifestPath, read.manifest, opts.bundleDir);
523
562
  if (!resolved.ok)
524
563
  return { ok: false, kind: 'io', message: `bundle: ${resolved.message}` };
525
- const collected = collectBundleFiles(resolved.dir, opts.manifestPath);
564
+ const collected = collectBundleFiles(resolved.dir, opts.manifestPath, {
565
+ entry: read.manifest.surface?.entry,
566
+ include: opts.include,
567
+ });
526
568
  if (!collected.ok)
527
569
  return { ok: false, kind: 'io', message: collected.message };
528
570
  // The server refuses a worker bundle without its backend (INVALID_WORKER_BUNDLE)
@@ -554,6 +596,8 @@ export async function runTileAppPublishPersonal(opts) {
554
596
  // go in ONE request, so the owner approves the publish once. Falls back to the
555
597
  // two-step path below on a server that predates the batch route.
556
598
  let uploadJson = {};
599
+ let installReport;
600
+ const workspaceId = workspaceIdOf(env);
557
601
  let appId = '';
558
602
  let batched = false;
559
603
  if (inWorkspacePod(env)) {
@@ -561,7 +605,13 @@ export async function runTileAppPublishPersonal(opts) {
561
605
  const res = await fetchImpl(`${base}/tileapps/personal/publish-batch`, {
562
606
  method: 'POST',
563
607
  headers,
564
- body: JSON.stringify({ id: localId, manifest: read.manifest, files: collected.files, ...(opts.live ? { live: true } : {}) }),
608
+ // `workspaceId`: this pod's workspace, so the server can move an existing
609
+ // install there to the new version (the install route's own checks apply).
610
+ body: JSON.stringify({
611
+ id: localId, manifest: read.manifest, files: collected.files,
612
+ ...(opts.live ? { live: true } : {}),
613
+ ...(workspaceId ? { workspaceId } : {}),
614
+ }),
565
615
  });
566
616
  const staged = await stagedForOwner(res, `publishing personal app '${localId}'`);
567
617
  if (staged)
@@ -575,6 +625,9 @@ export async function runTileAppPublishPersonal(opts) {
575
625
  const missingRoute = res.status === 404 && json.code !== 'feature-disabled';
576
626
  if (!missingRoute) {
577
627
  if (!res.ok) {
628
+ if (res.status === 409 && text.includes(STATIC_LIVE_DISABLED)) {
629
+ return { ok: false, kind: 'http', message: STATIC_LIVE_DISABLED_MESSAGE };
630
+ }
578
631
  if (res.status === 409 && text.includes(DYNAMIC_WORKERS_DISABLED)) {
579
632
  return { ok: false, kind: 'http', message: DYNAMIC_WORKERS_DISABLED_MESSAGE };
580
633
  }
@@ -585,6 +638,7 @@ export async function runTileAppPublishPersonal(opts) {
585
638
  return { ok: false, kind: 'http', message: 'publish response missing appId' };
586
639
  appId = json.appId;
587
640
  uploadJson = json.bundle ?? {};
641
+ installReport = json.install;
588
642
  batched = true;
589
643
  }
590
644
  }
@@ -625,6 +679,9 @@ export async function runTileAppPublishPersonal(opts) {
625
679
  return staged;
626
680
  if (!res.ok) {
627
681
  const body = await safeText(res);
682
+ if (res.status === 409 && body.includes(STATIC_LIVE_DISABLED)) {
683
+ return { ok: false, kind: 'http', message: STATIC_LIVE_DISABLED_MESSAGE };
684
+ }
628
685
  if (res.status === 409 && body.includes(DYNAMIC_WORKERS_DISABLED)) {
629
686
  return { ok: false, kind: 'http', message: DYNAMIC_WORKERS_DISABLED_MESSAGE };
630
687
  }
@@ -639,10 +696,27 @@ export async function runTileAppPublishPersonal(opts) {
639
696
  return { ok: false, kind: 'http', message: `bundle upload request failed: ${e.message}` };
640
697
  }
641
698
  }
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).';
699
+ const summary = `Published ${appId} (${collected.files.length} file${collected.files.length === 1 ? '' : 's'}, ${collected.totalBytes} bytes)`
700
+ + (collected.skipped.length > 0 ? `\n skipped (docs are not uploaded; --include <path> to upload one): ${collected.skipped.join(', ')}` : '');
701
+ const next = installNextLines(appId, workspaceId, installReport);
702
+ if (!isWorker && opts.live) {
703
+ // A static live edit: stored beside the published bundle, shown only on the owner's tile.
704
+ if (uploadJson.live !== true) {
705
+ return { ok: false, kind: 'http', message: `${appId}: the server did not store a live version; publish without --live, or check the deployment has live edits on` };
706
+ }
707
+ return {
708
+ ok: true,
709
+ output: [
710
+ summary,
711
+ ' live: true (owner-only preview)',
712
+ " Only your own tile shows this version (relaunch or reload the tile). Customers' portals and the published",
713
+ ' version are unchanged; publish without --live to ship it.',
714
+ ...next,
715
+ ].join('\n'),
716
+ };
717
+ }
644
718
  if (!isWorker)
645
- return { ok: true, output: `${summary}\n${next}` };
719
+ return { ok: true, output: [summary, ...next].join('\n') };
646
720
  // A worker app's bundle is stored either way; `publish` says whether its
647
721
  // backend made it, and `live` whether that backend runs on Dynamic Workers.
648
722
  // A version with no backend serves a UI whose /api/* is dead, so it is a failure.
@@ -664,12 +738,58 @@ export async function runTileAppPublishPersonal(opts) {
664
738
  else {
665
739
  lines.push(' backend: no worker placement report — the worker placement may be off on this deployment, so the backend was not published.');
666
740
  }
667
- lines.push(next);
741
+ lines.push(...next);
668
742
  return { ok: true, output: lines.join('\n') };
669
743
  }
670
744
  /** The refusal code (HTTP 409) for a live worker tile when Dynamic Workers is off on the deployment. */
671
745
  const DYNAMIC_WORKERS_DISABLED = 'dynamic-workers-disabled';
672
746
  export const DYNAMIC_WORKERS_DISABLED_MESSAGE = 'live worker tiles are not enabled on this deployment; publish without --live';
747
+ /** The refusal code (HTTP 409) for a live edit of an interface-only app where it is off. */
748
+ const STATIC_LIVE_DISABLED = 'static-live-disabled';
749
+ export const STATIC_LIVE_DISABLED_MESSAGE = 'live edits of interface-only apps are not enabled on this deployment; publish without --live';
750
+ /**
751
+ * This pod's workspace id (`WORKSPACE_ID`, set in every session pod), or
752
+ * undefined. Only when the API is the one the pod belongs to (production, or the
753
+ * API the pod was provisioned for): `$WORKSPACE_ID` names a workspace there,
754
+ * not on another API — the same rule `yolo deploy` follows.
755
+ */
756
+ export function workspaceIdOf(env, readFileImpl = defaultReadFile) {
757
+ const ws = (env.WORKSPACE_ID ?? '').trim().toLowerCase();
758
+ if (!inWorkspacePod(env) || !/^[a-f0-9]{24}$/.test(ws))
759
+ return undefined;
760
+ if (isProductionTarget(env))
761
+ return ws;
762
+ const provisioned = podProvisionedApiUrl(env, readFileImpl);
763
+ return provisioned && sameApiOrigin(provisioned, targetApiUrl(env)) ? ws : undefined;
764
+ }
765
+ /**
766
+ * The publish output's install line(s): what happened to the workspace install,
767
+ * and exactly ONE next command when one is needed.
768
+ */
769
+ export function installNextLines(appId, workspaceId, report) {
770
+ const ws = workspaceId ?? '<workspaceId>';
771
+ const install = `yolo tileapp install ${appId} --workspace ${ws}`;
772
+ const addTile = `yolo tileapp add-tile ${appId} --workspace ${ws}`;
773
+ switch (report?.status) {
774
+ case 'upgraded': {
775
+ const n = report.refreshedTileIds?.length ?? 0;
776
+ 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.`];
777
+ }
778
+ case 'current':
779
+ return [' install: this workspace already runs this version — nothing else to run.'];
780
+ case 'not-installed':
781
+ return [` next: ${install} && ${addTile}`];
782
+ case 'reconsent-required': {
783
+ const perms = [...(report.newRequiredPermissions ?? []), ...(report.stalePermissions ?? []).map((p) => `-${p}`)];
784
+ return [` next: ${install} (this version changes the app's permissions${perms.length ? `: ${perms.join(', ')}` : ''}, so it needs your consent again)`];
785
+ }
786
+ case 'failed':
787
+ return [` install: not moved to the new version (${report.error ?? 'the install step failed'})`, ` next: ${install}`];
788
+ default:
789
+ // No report: published outside a workspace pod, or a server that predates it.
790
+ return [` next: if it's already installed, ${install} moves the install to this version; if not, also run ${addTile}`];
791
+ }
792
+ }
673
793
  /**
674
794
  * Build the app image in-pod with podman, `save` it to an OCI archive in the
675
795
  * workspace, and hand it to common-api's MEDIATED push endpoint — common-api
@@ -805,7 +925,7 @@ async function publishRuntime(p) {
805
925
  return { ok: false, kind: 'http', message: 'publish-image response missing appId' };
806
926
  return {
807
927
  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).`,
928
+ output: [`Published runtime app ${json.appId}`, ` image: ${json.ref}:${json.tag}@${json.digest}`, ...installNextLines(json.appId, workspaceIdOf(p.env), undefined)].join('\n'),
809
929
  };
810
930
  }
811
931
  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.3.0",
4
4
  "description": "YOLO Studio CLI for workspace context, artifacts, personal apps and hosting.",
5
5
  "license": "MIT",
6
6
  "repository": {