@junoflow/cli 0.6.0 → 0.10.0

package/src/app-project.js

@@ -0,0 +1,133 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join, posix, relative, sep } from 'node:path';
+
+import { UserError } from './errors.js';
+import { readSourceFiles, readTestFiles } from './project.js';
+import {
+  baseVersionOf,
+  PAGE_TSCONFIG,
+  readBoundPackage,
+  readManifestFile,
+  writePackageJSON,
+} from './working-copy.js';
+
+/**
+ * An app working copy is the archive's own layout — src/ compiled, page/
+ * built at ingest, public/ served as is, test/ stored and never compiled —
+ * plus manifest.json, types/ (generated), page/tsconfig.json and
+ * package.json, whose `juno` block binds the directory to one app. The
+ * layout is the server's (POST /api/apps/scaffold); this module only knows
+ * what a command reads or writes back, and what it shares with a flow working
+ * copy lives in working-copy.js.
+ */
+export const SRC_DIR = 'src';
+export const PAGE_DIR = 'page';
+export const PUBLIC_DIR = 'public';
+export { PAGE_TSCONFIG };
+
+/**
+ * readAppProject reads what ingest takes: the manifest (parsed, so a broken
+ * one fails here with its parse error rather than as a server 422), src/,
+ * test/, page/ and public/ as one archive, the lockfile, and the binding in
+ * package.json.
+ *
+ * Ingest keys a version on the manifest's id, so a manifest whose id is not
+ * `juno.app_id` would make a second app rather than a version of this one.
+ * That is refused here, before anything is sent, as the flow ingest route
+ * refuses a manifest naming another flow.
+ */
+export async function readAppProject(cwd) {
+  const pkg = await readAppPackage(cwd);
+  const { manifest, manifestRaw } = await readManifestFile(cwd);
+  const appId = pkg.juno.app_id;
+  if (manifest?.id !== appId) {
+    throw new UserError(
+      `manifest.json's id is ${JSON.stringify(manifest?.id)}, but this working copy is app "${appId}" ` +
+        '(juno.app_id in package.json) — deploying it would create a second app rather than a version of this one. ' +
+        `Set the id back to "${appId}", or run \`juno app init <new-id>\` for a new app.`
+    );
+  }
+  return {
+    manifest,
+    manifestRaw,
+    files: {
+      ...(await readSourceFiles(cwd)),
+      ...(await readTestFiles(cwd)),
+      ...(await readPageFiles(cwd)),
+      ...(await readPublicFiles(cwd)),
+    },
+    lockfile: await readOptional(join(cwd, 'package-lock.json')),
+    packageJSON: pkg,
+    appId,
+    baseVersion: baseVersionOf(pkg),
+  };
+}
+
+/** readAppPackage is package.json, refusing a directory that is not an app working copy. */
+export function readAppPackage(cwd) {
+  return readBoundPackage(cwd, { kind: 'app', idKey: 'app_id' });
+}
+
+/**
+ * updateAppPackage rewrites an app working copy's package.json through
+ * `mutate`, keeping every key it does not touch (and their order).
+ */
+export async function updateAppPackage(cwd, mutate) {
+  const pkg = await readAppPackage(cwd);
+  mutate(pkg);
+  await writePackageJSON(cwd, pkg);
+}
+
+/**
+ * readPublicFiles walks public/ and returns repo-relative POSIX paths →
+ * content: every file, since all of public/ is served, except dotfiles
+ * (.DS_Store, an editor's swap file), which are the machine's and not the
+ * page's. The server enforces the caps and the reserved names.
+ */
+export function readPublicFiles(cwd) {
+  return readTree(cwd, PUBLIC_DIR);
+}
+
+/**
+ * readPageFiles is readPublicFiles for page/, less page/tsconfig.json. What
+ * may be in page/ (the entry document and .ts files) is the server's to
+ * enforce, so a stray file is sent and refused by name rather than dropped.
+ */
+export async function readPageFiles(cwd) {
+  const files = await readTree(cwd, PAGE_DIR);
+  delete files[PAGE_TSCONFIG];
+  return files;
+}
+
+/** readTree reads every file under dir but dotfiles, by repo-relative POSIX path. */
+async function readTree(cwd, dir) {
+  const files = {};
+  async function walk(dir) {
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return; // no such directory at all; ingest names a missing entry document
+    }
+    for (const entry of entries) {
+      if (entry.name.startsWith('.')) continue;
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(full);
+        continue;
+      }
+      const rel = relative(cwd, full).split(sep).join(posix.sep);
+      files[rel] = await readFile(full, 'utf8');
+    }
+  }
+  await walk(join(cwd, dir));
+  return files;
+}
+
+async function readOptional(path) {
+  try {
+    return await readFile(path, 'utf8');
+  } catch {
+    return null;
+  }
+}

package/src/authoring-skills.js

@@ -4,10 +4,11 @@ import { warnIfStale } from './installed-skill.js';
  * The kinds of working copy with an authoring skill index, and the heading
  * each is printed under. The index itself is the server's
  * (GET /api/skills?authoring=<kind>): the same name and description lines the
- * in-app flow and integration authors are given, so it cannot drift from the
+ * in-app app, flow and integration authors are given, so it cannot drift from the
  * skills.
  */
 export const AUTHORING_HEADINGS = {
+  app: 'Skills for writing an app',
   flow: 'Skills for writing a flow',
   integration: 'Skills for writing an integration',
 };

package/src/commands/app-check.js

@@ -0,0 +1,75 @@
+import { connect } from '../api.js';
+import { readAppProject } from '../app-project.js';
+import { printDiagnosticsJSON, printJSON } from '../diagnostics.js';
+import { DiagnosticsError } from '../errors.js';
+import { EXIT_CONFLICT } from '../exit.js';
+import { runLocalChecks } from './check.js';
+import { warnOnDependencyDrift } from './flow-check.js';
+
+export const APP_CHECK_USAGE = 'juno app check [--skip-local] [--json]';
+
+/**
+ * `juno app check` — local tsc and eslint, then an ingest with
+ * `activate: false`: the verification deploy runs, stored as a draft and not
+ * activated, so the page can be opened at its `~draft/` URL before anyone
+ * else sees it. Unlike a flow's check this stores something — an app's draft
+ * is how it is previewed — which is why its effect is `change`. The draft's
+ * handlers run for real: a preview is live.
+ *
+ * It sends `juno.base_version`. The server never refuses a preview, so a stale
+ * copy still stores its draft; the answer's `stale_base` is the sentence a
+ * deploy would be refused with, printed after the preview, and the exit is 4
+ * — the code every kind's check gives a stale copy.
+ *
+ * --json prints the route's body (or the 422's diagnostics) on stdout and
+ * nothing else; the local tools' own output goes to stderr.
+ */
+export async function appCheck(argv, io) {
+  const project = await readAppProject(io.cwd);
+  const failed = !argv['skip-local'] && (await runLocalChecks(argv, io));
+  warnOnDependencyDrift(project, io);
+
+  const { target, client } = await connect(argv, io);
+  let result;
+  try {
+    result = await client.ingestApp(project, {
+      activate: false,
+      baseVersion: project.baseVersion,
+    });
+  } catch (err) {
+    if (argv.json && err instanceof DiagnosticsError) {
+      return printDiagnosticsJSON(err, io);
+    }
+    throw err;
+  }
+
+  if (argv.json) {
+    printJSON(result, io);
+  } else {
+    for (const w of result.warnings ?? []) io.warn(`warning: ${w}`);
+    io.log(
+      `${result.id}: verified and stored as draft v${result.version} on ${target}`
+    );
+    printPreview(result, io);
+    if (result.stale_base) io.error(result.stale_base);
+  }
+  if (result.stale_base) return EXIT_CONFLICT;
+  return failed ? 1 : 0;
+}
+
+/**
+ * The draft's preview URL is the app's URL with `~draft/` on the end. Juno
+ * reports no URL while the apps_url site setting is unset, and the CLI does
+ * not guess one: the apps listener's address is not the hostname a proxy
+ * puts in front of it.
+ */
+function printPreview(result, io) {
+  if (result.url) {
+    io.log(`preview: ${result.url}~draft/`);
+    return;
+  }
+  io.warn(
+    'no preview URL: apps_url is not set on this instance (Settings → Site). ' +
+      `Once it is, the draft is served at <apps_url>/${result.id}/~draft/`
+  );
+}

package/src/commands/app-deploy.js

@@ -0,0 +1,113 @@
+import { join } from 'node:path';
+
+import { connect } from '../api.js';
+import {
+  PAGE_DIR,
+  PUBLIC_DIR,
+  readAppProject,
+  SRC_DIR,
+  updateAppPackage,
+} from '../app-project.js';
+import { printDiagnosticsJSON, printJSON } from '../diagnostics.js';
+import { DiagnosticsError } from '../errors.js';
+import { deployOnChange } from '../watch.js';
+import {
+  MANIFEST,
+  manifestText,
+  typeFiles,
+  writeChangedFiles,
+} from '../working-copy.js';
+
+export const APP_DEPLOY_USAGE = 'juno app deploy [--watch] [--force] [--json]';
+
+/**
+ * `juno app deploy` — upload manifest.json, src/, page/ and public/ to
+ * POST /api/apps/ingest, which verifies them through the same path the
+ * in-app assistant's submit_code uses, stores a version and activates it.
+ *
+ * It sends `juno.base_version`, so an app changed elsewhere since this copy
+ * was pulled is a 409 (exit 4) rather than a silent overwrite; --force sends
+ * none and replaces whatever is active.
+ *
+ * When the version binds something the previous one did not, the answer's
+ * `widened_links` says how many active app links it widens, and a line says so.
+ *
+ * On success it writes back what the server now holds: the canonical
+ * manifest, the three files under types/, and the new juno.base_version.
+ * --watch redeploys on every save to src/, page/, public/ or manifest.json,
+ * re-reading the base each time, so the loop is checked against its own
+ * previous deploy rather than refused by it.
+ */
+export async function appDeploy(argv, io) {
+  const { target, client } = await connect(argv, io);
+  if (!argv.watch) {
+    const project = await readAppProject(io.cwd);
+    try {
+      await deployProject(client, project, argv, io, target);
+    } catch (err) {
+      if (argv.json && err instanceof DiagnosticsError) {
+        return printDiagnosticsJSON(err, io);
+      }
+      throw err;
+    }
+    return 0;
+  }
+
+  // A deploy writes manifest.json back, which the watcher sees. Remembering
+  // what was last deployed makes that echo — and any save that changed
+  // nothing — a no-op instead of another version.
+  let last = null;
+  return deployOnChange({
+    io,
+    target,
+    paths: [
+      { path: join(io.cwd, SRC_DIR), recursive: true },
+      { path: join(io.cwd, PAGE_DIR), recursive: true },
+      { path: join(io.cwd, PUBLIC_DIR), recursive: true },
+      { path: join(io.cwd, MANIFEST) },
+    ],
+    once: async () => {
+      const project = await readAppProject(io.cwd);
+      const key = JSON.stringify([project.manifestRaw, project.files]);
+      if (key === last) return;
+      const after = await deployProject(client, project, argv, io, target);
+      last = JSON.stringify([after.manifestRaw, project.files]);
+    },
+  });
+}
+
+async function deployProject(client, project, argv, io, target) {
+  const result = await client.ingestApp(project, {
+    baseVersion: argv.force ? undefined : project.baseVersion,
+  });
+
+  const manifestRaw = manifestText(result.manifest);
+  const written = await writeChangedFiles(io.cwd, {
+    [MANIFEST]: manifestRaw,
+    ...typeFiles(result.types),
+  });
+  if (project.baseVersion !== result.version) {
+    await updateAppPackage(io.cwd, (pkg) => {
+      pkg.juno.base_version = result.version;
+    });
+    written.push('package.json');
+  }
+
+  if (argv.json) {
+    printJSON(result, io);
+  } else {
+    for (const w of result.warnings ?? []) io.warn(`warning: ${w}`);
+    const files = written.length ? ` (${written.sort().join(', ')})` : '';
+    io.log(`deployed ${result.id} v${result.version} to ${target}${files}`);
+    if (result.url) io.log(`open: ${result.url}`);
+    // A notice, not a refusal: the version is already live. It binds something
+    // the previous one did not, and every active app link gets it too.
+    const widened = result.widened_links ?? 0;
+    if (widened > 0) {
+      io.warn(
+        `This version widens what ${widened} active ${widened === 1 ? 'link' : 'links'} can do.`
+      );
+    }
+  }
+  return { manifestRaw };
+}

package/src/commands/app-dev.js

@@ -0,0 +1,141 @@
+import { readAppPackage } from '../app-project.js';
+import { createBuilder } from '../app-dev/build.js';
+import { createDevHarness } from '../app-dev/harness.js';
+import { createPanel } from '../app-dev/panel.js';
+import { createDevServer } from '../app-dev/server.js';
+import { createLive } from '../app-dev/stream.js';
+import { watchApp } from '../app-dev/watch.js';
+import { UsageError, UserError } from '../errors.js';
+import { readManifestFile } from '../working-copy.js';
+
+export const APP_DEV_USAGE = 'juno app dev [--port <n>] [--scenario <file>]';
+
+/** The port `juno app dev` listens on without --port. */
+export const DEFAULT_DEV_PORT = 8090;
+
+/**
+ * `juno app dev` — serve this app on localhost, offline, on mocked data
+ * (old-docs/design-docs/plan-local-dev-6-app-dev-server.md). The page is
+ * page/ as written, its modules bundled per request; the handlers run in
+ * Node through the working copy's own appHarness; the world is the
+ * --scenario file, or empty. It never reads `juno.target`, never connects to
+ * an instance and never reads a credential, so its effect is `local`.
+ *
+ * Bound to 127.0.0.1 only. It runs until SIGINT (or io.signal aborts), then
+ * closes the server and removes its temp directory.
+ */
+export async function appDev(argv, io) {
+  const port = parsePort(argv.port);
+  const dev = await startAppDev({
+    cwd: io.cwd,
+    port,
+    scenario: argv.scenario,
+    log: io.error,
+  });
+  io.log(
+    `juno app dev: ${dev.id} on http://localhost:${dev.port}/  ` +
+      `(${dev.harness.scenario ? `scenario: ${dev.harness.scenario.path}` : 'no scenario'})`
+  );
+  await new Promise((resolve) => {
+    const stop = () => {
+      process.off('SIGINT', stop);
+      io.signal?.removeEventListener('abort', stop);
+      resolve();
+    };
+    process.once('SIGINT', stop);
+    io.signal?.addEventListener('abort', stop, { once: true });
+    if (io.signal?.aborted) stop();
+  });
+  await dev.close();
+  return 0;
+}
+
+/**
+ * startAppDev reads the working copy, resolves esbuild and the testkit from
+ * it, and starts the server on port (0 picks a free one), with the live
+ * stream, the panel and the watcher wired in. It resolves to
+ * `{id, port, server, harness, builder, live, panel, close}`; `server` is
+ * createDevServer's object, whose `routes` a caller may extend. `pingMs` and
+ * `debounceMs` exist for tests.
+ */
+export async function startAppDev({
+  cwd,
+  port,
+  scenario,
+  log = () => {},
+  pingMs,
+  debounceMs,
+}) {
+  await readAppPackage(cwd);
+  const { manifest } = await readManifestFile(cwd);
+  if (typeof manifest?.id !== 'string' || manifest.id === '') {
+    throw new UserError('manifest.json has no id');
+  }
+
+  const builder = await createBuilder(cwd);
+  try {
+    const harness = await createDevHarness({ cwd, manifest, builder });
+    if (scenario !== undefined) await harness.useScenario(scenario);
+    const live = createLive({ dev: harness, pingMs });
+    const panel = createPanel({
+      cwd,
+      dev: harness,
+      builder,
+      live,
+      pingMs,
+      log,
+    });
+    await panel.noteScenario();
+    const server = createDevServer({
+      cwd,
+      dev: harness,
+      builder,
+      log,
+      routes: { stream: live.serve, dev: panel.route, shell: panel.shell },
+    });
+    let bound;
+    try {
+      bound = await server.listen(port);
+    } catch (err) {
+      if (err.code === 'EADDRINUSE') {
+        throw new UserError(
+          `port ${port} is in use — pass --port <n> to pick another`
+        );
+      }
+      throw err;
+    }
+    const watcher = watchApp(cwd, panel.watch, { debounceMs });
+    return {
+      id: manifest.id,
+      port: bound,
+      server,
+      harness,
+      builder,
+      live,
+      panel,
+      async close() {
+        watcher.close();
+        await panel.settled();
+        live.close();
+        panel.close();
+        await server.close();
+        await builder.close();
+      },
+    };
+  } catch (err) {
+    await builder.close();
+    throw err;
+  }
+}
+
+function parsePort(value) {
+  if (value === undefined) return DEFAULT_DEV_PORT;
+  const port = Number(value);
+  // 0 is the operating system's pick; the printed URL names the port it made.
+  if (!/^\d+$/.test(String(value)) || port > 65535) {
+    throw new UsageError(
+      `--port must be a port number from 0 to 65535, got ${JSON.stringify(value)}`
+    );
+  }
+  return port;
+}

package/src/commands/app-gen-types.js

@@ -0,0 +1,37 @@
+import { connect } from '../api.js';
+import { readAppPackage } from '../app-project.js';
+import { UserError } from '../errors.js';
+import {
+  readManifestFile,
+  typeFiles,
+  writeChangedFiles,
+} from '../working-copy.js';
+
+export const APP_GEN_TYPES_USAGE = 'juno app gen-types';
+
+/**
+ * `juno app gen-types` — regenerate the three files under types/ from
+ * manifest.json against the instance's live catalog: app-env.d.ts (what
+ * src/app.ts is checked against), app-client.d.ts (`juno` as the page sees
+ * it) and app-api.d.ts. manifest.json itself is left alone. Stale types
+ * cannot ship regardless, because ingest regenerates them.
+ */
+export async function appGenTypes(argv, io) {
+  await readAppPackage(io.cwd);
+  const { manifest } = await readManifestFile(io.cwd);
+  const { client } = await connect(argv, io);
+  const generated = await client.typegenApp(manifest);
+  const files = typeFiles(generated.types);
+  if (!Object.keys(files).length) {
+    throw new UserError(
+      `${client.target} answered no .d.ts files for this manifest`
+    );
+  }
+  const written = await writeChangedFiles(io.cwd, files);
+  io.log(
+    written.length
+      ? `wrote ${written.join(', ')}`
+      : `${Object.keys(files).sort().join(', ')} already up to date`
+  );
+  return 0;
+}

package/src/commands/app-init.js

@@ -0,0 +1,46 @@
+import { resolve } from 'node:path';
+
+import { connect } from '../api.js';
+import { printAuthoringIndex } from '../authoring-skills.js';
+import { UsageError, UserError } from '../errors.js';
+import { writeChangedFiles } from '../working-copy.js';
+import { exists } from './init.js';
+
+export const APP_INIT_USAGE = 'juno app init <id> [--here]';
+
+/**
+ * `juno app init <id>` — a working copy of the app's active version, or a
+ * stub with one handler for an id with none, written into ./<id> (or the
+ * current directory with --here).
+ *
+ * Every file comes from POST /api/apps/scaffold, the single generator of an
+ * app working copy: the CLI writes what it is handed and holds no copy of the
+ * layout, the script lines or the types. After the next steps it prints the
+ * app author's skill index, which is where an external agent starts.
+ */
+export async function appInit(argv, io) {
+  const [id, ...extra] = argv._;
+  if (!id || extra.length > 0) {
+    throw new UsageError(`usage: ${APP_INIT_USAGE}`);
+  }
+
+  const dir = resolve(io.cwd, argv.here ? '.' : id);
+  if (!argv.here && (await exists(dir))) {
+    throw new UserError(`${dir} already exists`);
+  }
+
+  const { target, client } = await connect(argv, io);
+  // The id is validated server-side, by the validator ingest runs: one answer
+  // to "is this a valid app id".
+  const files = await client.scaffoldApp(id, { target });
+  await writeChangedFiles(dir, files);
+
+  io.log(`created ${dir}`);
+  io.log('');
+  io.log(argv.here ? 'npm install' : `cd ${id} && npm install`);
+  io.log('npm test');
+  io.log('npm run check    # stores a draft and prints its preview URL');
+  io.log('npm run deploy');
+  await printAuthoringIndex('app', client, target, io);
+  return 0;
+}

package/src/commands/app-pull.js

@@ -0,0 +1,106 @@
+import { connect } from '../api.js';
+import { readAppPackage, updateAppPackage } from '../app-project.js';
+import { UserError } from '../errors.js';
+import {
+  baseArtifactPaths,
+  baseVersionOf,
+  MANIFEST,
+  manifestText,
+  PACKAGE_JSON,
+  pullArtifacts,
+  requireCleanTree,
+  setDependencies,
+  writeChangedFiles,
+} from '../working-copy.js';
+
+export const APP_PULL_USAGE = 'juno app pull [--force]';
+
+/**
+ * `juno app pull` — make the working copy's artifact files the app's active
+ * version: manifest.json and every file under src/, test/, page/ and public/,
+ * exactly as the version stores them (GET /api/apps/{id}/versions/{v}), never
+ * as the scaffold renders them. types/ is generated, so it comes from
+ * POST /api/apps/scaffold, which also names the active version. In
+ * package.json only `dependencies` (the manifest's) and `juno.base_version`
+ * are Juno's; `scripts` and every other key are the author's and stay.
+ *
+ * A local file is deleted only when the base version (`juno.base_version`)
+ * had it and the pulled one does not; a file neither has is one not deployed
+ * yet, and stays. page/tsconfig.json and the other project files are never
+ * written or deleted.
+ *
+ * It refuses a dirty git tree without --force, as the other kinds' pull
+ * does: an uncommitted edit is the one thing nothing can get back.
+ */
+export async function appPull(argv, io) {
+  const pkg = await readAppPackage(io.cwd);
+  const appId = pkg.juno.app_id;
+
+  await requireCleanTree(io.cwd, {
+    force: argv.force,
+    overwrites: `${MANIFEST}, src/, test/, page/, public/ and types/`,
+    io,
+  });
+
+  const { target, client } = await connect(argv, io);
+  const files = await client.scaffoldApp(appId, { target });
+  let scaffoldPkg;
+  try {
+    scaffoldPkg = JSON.parse(files[PACKAGE_JSON]);
+  } catch {
+    throw new UserError(
+      `${target} answered a working copy with no readable ${PACKAGE_JSON}`
+    );
+  }
+  const version = scaffoldPkg.juno?.base_version;
+  const noActive = () =>
+    new UserError(
+      `${appId} has no active version on ${target} — nothing to pull`
+    );
+  // No base_version is the scaffold's stub for an app with no active
+  // version; writing it over the author's work would lose it for nothing.
+  if (!Number.isInteger(version)) throw noActive();
+
+  // Everything is fetched before anything is written, so a failure leaves
+  // the working copy as it was.
+  const detail = await client.getAppVersion(appId, version);
+  if (!detail) throw noActive();
+  const stored = { [MANIFEST]: manifestText(detail.manifest), ...detail.files };
+  const base = await baseArtifactPaths({
+    base: baseVersionOf(pkg),
+    version,
+    stored,
+    read: async (v) => {
+      const b = await client.getAppVersion(appId, v);
+      return b ? [MANIFEST, ...Object.keys(b.files ?? {})] : null;
+    },
+    id: appId,
+    target,
+    io,
+  });
+
+  const { written, removed } = await pullArtifacts(io.cwd, {
+    stored,
+    base,
+    kind: 'app',
+  });
+  written.push(
+    ...(await writeChangedFiles(
+      io.cwd,
+      Object.fromEntries(
+        Object.entries(files).filter(([name]) => name.startsWith('types/'))
+      )
+    ))
+  );
+  await updateAppPackage(io.cwd, (p) => {
+    setDependencies(p, detail.manifest);
+    p.juno.base_version = version;
+  });
+  written.push(PACKAGE_JSON);
+
+  io.log(
+    `pulled ${appId} v${version} from ${target} (${written.sort().join(', ')})`
+  );
+  if (removed.length) io.log(`removed ${removed.join(', ')}`);
+  return 0;
+}