@junoflow/cli 0.3.0 → 0.9.0

package/src/working-copy.js

@@ -0,0 +1,262 @@
+import { execFile } from 'node:child_process';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { promisify } from 'node:util';
+
+import { safeRelative } from './commands/init.js';
+import { UserError } from './errors.js';
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * What every working copy bound by package.json's `juno` block shares — a
+ * flow's (flow-project.js) and an app's (app-project.js): reading the
+ * manifest and the binding, writing back what a route answered, and the
+ * clean-tree check before a pull. Pulling itself (pullArtifacts) is shared
+ * with an integration's working copy too. The layout is the server's
+ * (POST /api/{flows,apps}/scaffold); this module knows only the names a
+ * command reads or writes back, and which of them are artifact files.
+ */
+export const MANIFEST = 'manifest.json';
+export const PACKAGE_JSON = 'package.json';
+
+/**
+ * page/tsconfig.json is a project file, not part of the page: the scaffold
+ * writes it, deploy never sends it (ingest would refuse it), and pull never
+ * writes or removes it.
+ */
+export const PAGE_TSCONFIG = 'page/tsconfig.json';
+
+/**
+ * The directories whose files a version stores, per kind, beside
+ * manifest.json. Everything else in a working copy is generated (types/) or
+ * a project file (tsconfig.json, README.md, package.json …) that no pull
+ * writes or deletes.
+ */
+const ARTIFACT_DIRS = {
+  flow: ['src/', 'test/'],
+  integration: ['src/', 'test/'],
+  app: ['src/', 'test/', 'page/', 'public/'],
+};
+
+/** isArtifactPath reports whether a `kind` version stores the file at path. */
+export function isArtifactPath(kind, path) {
+  if (path === MANIFEST) return true;
+  if (path === PAGE_TSCONFIG) return false;
+  return ARTIFACT_DIRS[kind].some((dir) => path.startsWith(dir));
+}
+
+/**
+ * pullArtifacts makes a working copy's artifact files the pulled version's.
+ * `stored` is that version's artifact files, path → content, as the version
+ * stores them and never as a scaffold renders them (a scaffold adds init-only
+ * files). Each one whose content differs is written.
+ *
+ * `base` is the artifact paths of the version the copy was pulled from or last
+ * deployed (`juno.base_version`), or null. A file is deleted only when the base
+ * had it and the pulled version does not: that is a file deleted in Juno. A
+ * file neither version has is one the author has not deployed yet, and stays.
+ * With no base, nothing is deleted. Returns `{written, removed}`, each sorted.
+ */
+export async function pullArtifacts(cwd, { stored, base, kind }) {
+  const written = await writeChangedFiles(cwd, stored);
+  const removed = [];
+  for (const path of base ?? []) {
+    if (Object.hasOwn(stored, path) || !isArtifactPath(kind, path)) continue;
+    try {
+      await rm(join(cwd, safeRelative(path)));
+    } catch (err) {
+      if (err.code === 'ENOENT') continue; // already gone locally
+      throw err;
+    }
+    removed.push(path);
+  }
+  return { written, removed: removed.sort() };
+}
+
+/**
+ * baseArtifactPaths is pullArtifacts' `base`: null when the copy records no
+ * base, the pulled version's own paths when the base is that version, and
+ * otherwise what `read(base)` answers — the base version's artifact paths, or
+ * null when the instance no longer has it. Pull then deletes nothing, and says
+ * so on stderr.
+ */
+export async function baseArtifactPaths({
+  base,
+  version,
+  stored,
+  read,
+  id,
+  target,
+  io,
+}) {
+  if (base === undefined) return null;
+  if (base === version) return Object.keys(stored);
+  const paths = await read(base);
+  if (paths === null) {
+    io.warn(
+      `${id} v${base}, this copy's base_version, no longer exists on ${target} — no local file was removed`
+    );
+  }
+  return paths;
+}
+
+/**
+ * setDependencies makes package.json's `dependencies` the manifest's, in name
+ * order as the scaffold writes them, or removes the key when the manifest
+ * declares none. It is the one place pull keeps the two in step.
+ */
+export function setDependencies(pkg, manifest) {
+  const deps = manifest?.dependencies;
+  if (deps && typeof deps === 'object' && Object.keys(deps).length) {
+    pkg.dependencies = Object.fromEntries(
+      Object.keys(deps)
+        .sort()
+        .map((name) => [name, deps[name]])
+    );
+  } else {
+    delete pkg.dependencies;
+  }
+}
+
+/** readManifestFile is manifest.json, as bytes and parsed. */
+export async function readManifestFile(cwd) {
+  const manifestRaw = await readText(cwd, MANIFEST);
+  try {
+    return { manifest: JSON.parse(manifestRaw), manifestRaw };
+  } catch (err) {
+    throw new UserError(`${MANIFEST} is not valid JSON: ${err.message}`);
+  }
+}
+
+/**
+ * readBoundPackage is package.json, refusing a directory that is not a
+ * `kind` working copy (no string `juno.<idKey>`) — every command but `init`
+ * acts on the current directory, and running one from the wrong place should
+ * say so rather than fail on a missing file.
+ */
+export async function readBoundPackage(cwd, { kind, idKey }) {
+  let pkg = null;
+  try {
+    pkg = JSON.parse(await readFile(join(cwd, PACKAGE_JSON), 'utf8'));
+  } catch {
+    // Missing or unreadable: reported below as not a working copy.
+  }
+  if (typeof pkg?.juno?.[idKey] !== 'string' || pkg.juno[idKey] === '') {
+    throw new UserError(
+      `${cwd} is not ${article(kind)} ${kind} working copy (no juno.${idKey} in package.json) — ` +
+        `run \`juno ${kind} init <id>\` to make one`
+    );
+  }
+  return pkg;
+}
+
+/** baseVersionOf is `juno.base_version`, or undefined when there is none. */
+export function baseVersionOf(pkg) {
+  return Number.isInteger(pkg.juno.base_version)
+    ? pkg.juno.base_version
+    : undefined;
+}
+
+/**
+ * writePackageJSON writes package.json with a two-space indent and a trailing
+ * newline — the way npm writes it — so, with every key the caller did not
+ * touch left in place, the diff is only what changed.
+ */
+export async function writePackageJSON(cwd, pkg) {
+  await writeFile(
+    join(cwd, PACKAGE_JSON),
+    `${JSON.stringify(pkg, null, 2)}\n`,
+    'utf8'
+  );
+}
+
+/**
+ * writeChangedFiles writes files by working-copy path, creating directories
+ * as needed and skipping a file whose content is already what is on disk, so
+ * a watcher does not see a write that changed nothing. Returns the paths it
+ * wrote, sorted.
+ */
+export async function writeChangedFiles(cwd, files) {
+  const written = [];
+  for (const [rel, content] of Object.entries(files)) {
+    const path = join(cwd, safeRelative(rel));
+    let current = null;
+    try {
+      current = await readFile(path, 'utf8');
+    } catch {
+      // Not there yet.
+    }
+    if (current === content) continue;
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, content, 'utf8');
+    written.push(rel);
+  }
+  return written.sort();
+}
+
+/** The canonical manifest a route answered, as manifest.json holds it. */
+export function manifestText(manifest) {
+  return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+
+/**
+ * The .d.ts files of a route's `types`. Filtering by extension rather than
+ * naming them keeps a future file working without a CLI release.
+ */
+export function typeFiles(types) {
+  return Object.fromEntries(
+    Object.entries(types ?? {}).filter(([name]) => name.endsWith('.d.ts'))
+  );
+}
+
+/**
+ * requireCleanTree is pull's guard: without --force it refuses a dirty git
+ * tree, because an uncommitted edit is the one thing nothing can get back,
+ * and outside git it warns that `overwrites` has no undo.
+ */
+export async function requireCleanTree(cwd, { force, overwrites, io }) {
+  if (force) return;
+  const dirty = await dirtyPaths(cwd);
+  if (dirty === null) {
+    io.warn(
+      `not a git repository — pull will overwrite ${overwrites} with no undo`
+    );
+  } else if (dirty.length > 0) {
+    throw new UserError(
+      `working tree has uncommitted changes:\n${dirty.map((p) => `  ${p}`).join('\n')}\n` +
+        'Commit or stash them, or pass --force to overwrite.'
+    );
+  }
+}
+
+/**
+ * Returns the paths git reports as changed, [] for a clean tree, or null when
+ * this is not a git repository at all — three states the caller treats
+ * differently, so they must not collapse into a boolean.
+ */
+export async function dirtyPaths(cwd) {
+  try {
+    const { stdout } = await execFileAsync('git', ['status', '--porcelain'], {
+      cwd,
+    });
+    return stdout
+      .split('\n')
+      .map((line) => line.trim())
+      .filter(Boolean);
+  } catch {
+    return null;
+  }
+}
+
+export async function readText(cwd, name) {
+  try {
+    return await readFile(join(cwd, name), 'utf8');
+  } catch {
+    throw new UserError(`no ${name} in ${cwd}`);
+  }
+}
+
+function article(word) {
+  return /^[aeiou]/.test(word) ? 'an' : 'a';
+}

package/tsconfig.page.json

@@ -0,0 +1,15 @@
+{
+  "//": "The compiler options Juno type-checks an app's page/ with server-side: tsconfig.base.json for the browser, with the DOM's types and no @types package. internal/verify's tsconfig_preset_test.go asserts this file and verify.PageCompilerOptions() are identical. Extend it from page/tsconfig.json; do not fork it.",
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "types": []
+  }
+}

package/verbs.json

@@ -0,0 +1,276 @@
+{
+  "commands": [
+    {
+      "command": "discover",
+      "tool": "discover",
+      "id_field": "query",
+      "flags": {
+        "kind": { "field": "kinds", "type": "string", "multiple": true }
+      },
+      "naming_exception": "searches every kind, so it has no group"
+    },
+    {
+      "command": "related",
+      "tool": "get_related",
+      "positional": "kind:id",
+      "flags": { "degree": { "field": "degree", "type": "integer" } },
+      "naming_exception": "takes any kind, so it has no group"
+    },
+    { "command": "state get", "tool": "get_state", "id_field": "id" },
+    {
+      "command": "state get-history",
+      "tool": "get_state_history",
+      "id_field": "id"
+    },
+    {
+      "command": "state get-layers",
+      "tool": "get_state_layers",
+      "id_field": "id"
+    },
+    { "command": "state evaluate-level", "tool": "evaluate_level" },
+    {
+      "command": "state preview-layers",
+      "tool": "edit_state_layers",
+      "id_field": "id",
+      "fixed_input": { "dry_run": true },
+      "effect": "read",
+      "naming_exception": "fixes dry_run: true on edit_state_layers, so a permission rule can allow the preview and not the edit"
+    },
+    { "command": "state create", "tool": "create_state", "id_field": "id" },
+    {
+      "command": "state edit-layers",
+      "tool": "edit_state_layers",
+      "id_field": "id",
+      "fixed_input": { "dry_run": false }
+    },
+    {
+      "command": "state set-value",
+      "tool": "set_state_value",
+      "id_field": "id"
+    },
+    { "command": "state claim", "tool": "claim_state", "id_field": "id" },
+    { "command": "state release", "tool": "release_state", "id_field": "id" },
+    { "command": "flow get", "tool": "get_flow", "id_field": "id" },
+    {
+      "command": "flow set-enabled",
+      "tool": "set_flow_enabled",
+      "id_field": "flow_id"
+    },
+    {
+      "command": "flow trigger",
+      "tool": "trigger_flow",
+      "id_field": "flow_id"
+    },
+    {
+      "command": "flow fire-trigger",
+      "tool": "fire_trigger",
+      "id_field": "flow_id"
+    },
+    {
+      "command": "flow init",
+      "effect": "read",
+      "working_copy": true,
+      "summary": "Write a working copy of a flow (or a stub for a new id) into ./<id>"
+    },
+    {
+      "command": "flow gen-types",
+      "effect": "read",
+      "working_copy": true,
+      "summary": "Regenerate types/ from manifest.json"
+    },
+    {
+      "command": "flow check",
+      "effect": "read",
+      "working_copy": true,
+      "summary": "Typecheck and lint locally, then verify against Juno without deploying"
+    },
+    {
+      "command": "flow deploy",
+      "effect": "change",
+      "working_copy": true,
+      "summary": "Verify, commit and activate the working copy as the flow's next version"
+    },
+    {
+      "command": "flow pull",
+      "effect": "read",
+      "working_copy": true,
+      "summary": "Overwrite the working copy with the flow's active version"
+    },
+    {
+      "command": "flow fixture",
+      "effect": "read",
+      "working_copy": true,
+      "summary": "Write a test fixture from a recorded run"
+    },
+    { "command": "run list", "tool": "list_runs" },
+    { "command": "run get", "tool": "get_run", "id_field": "run_id" },
+    {
+      "command": "integration get",
+      "tool": "get_integration",
+      "id_field": "id"
+    },
+    {
+      "command": "integration configure",
+      "tool": "configure_integration",
+      "id_field": "id"
+    },
+    { "command": "integration install", "tool": "install_integration" },
+    {
+      "command": "integration run-schedule",
+      "tool": "run_integration_schedule",
+      "id_field": "integration"
+    },
+    {
+      "command": "integration init",
+      "effect": "read",
+      "working_copy": true,
+      "summary": "Write a working copy of an install (or a starter for a new id) into ./<id>"
+    },
+    {
+      "command": "integration gen-types",
+      "effect": "read",
+      "working_copy": true,
+      "summary": "Regenerate types/ from manifest.json"
+    },
+    {
+      "command": "integration verify-types",
+      "effect": "read",
+      "working_copy": true,
+      "summary": "Check offline that types/ matches manifest.json"
+    },
+    {
+      "command": "integration check",
+      "effect": "read",
+      "working_copy": true,
+      "summary": "Typecheck and lint locally, then verify against Juno without deploying"
+    },
+    {
+      "command": "integration deploy",
+      "effect": "change",
+      "working_copy": true,
+      "summary": "Verify, commit and activate the working copy as the install's next version"
+    },
+    {
+      "command": "integration pull",
+      "effect": "read",
+      "working_copy": true,
+      "summary": "Overwrite manifest.json, src/, test/ and types/ with the active version"
+    },
+    { "command": "device list", "tool": "list_devices" },
+    { "command": "device get", "tool": "get_device", "id_field": "id" },
+    { "command": "device preview", "tool": "preview_device" },
+    { "command": "device write", "tool": "write_device" },
+    { "command": "device suspend", "tool": "suspend_device", "id_field": "id" },
+    { "command": "device release", "tool": "release_device", "id_field": "id" },
+    { "command": "control write", "tool": "write_control" },
+    { "command": "control use", "tool": "use_control", "id_field": "id" },
+    {
+      "command": "control release",
+      "tool": "release_control",
+      "id_field": "id"
+    },
+    { "command": "app get", "tool": "get_app", "id_field": "id" },
+    {
+      "command": "app list-invocations",
+      "tool": "list_app_invocations",
+      "id_field": "id",
+      "flags": { "limit": { "field": "limit", "type": "integer" } }
+    },
+    {
+      "command": "app init",
+      "effect": "read",
+      "working_copy": true,
+      "summary": "Write a working copy of an app (or a stub for a new id) into ./<id>"
+    },
+    {
+      "command": "app gen-types",
+      "effect": "read",
+      "working_copy": true,
+      "summary": "Regenerate types/ from manifest.json"
+    },
+    {
+      "command": "app check",
+      "effect": "change",
+      "working_copy": true,
+      "summary": "Typecheck and lint locally, then store the working copy as a draft and print its preview URL"
+    },
+    {
+      "command": "app deploy",
+      "effect": "change",
+      "working_copy": true,
+      "summary": "Verify, commit and activate the working copy as the app's next version"
+    },
+    {
+      "command": "app pull",
+      "effect": "read",
+      "working_copy": true,
+      "summary": "Overwrite the working copy with the app's active version"
+    },
+    {
+      "command": "app dev",
+      "effect": "local",
+      "working_copy": true,
+      "summary": "Serve this app locally on mocked data"
+    },
+    { "command": "finding get", "tool": "get_finding", "id_field": "slug" },
+    { "command": "webhook list", "tool": "list_webhooks" },
+    {
+      "command": "webhook get-deliveries",
+      "tool": "get_webhook_deliveries",
+      "id_field": "id"
+    },
+    { "command": "webhook write", "tool": "write_webhook", "id_field": "id" },
+    { "command": "webhook fire", "tool": "fire_webhook", "id_field": "id" },
+    { "command": "credential list", "tool": "list_credentials" },
+    {
+      "command": "ha get-entity",
+      "tool": "get_entity",
+      "id_field": "entity_id"
+    },
+    {
+      "command": "ha get-entity-history",
+      "tool": "get_entity_history",
+      "id_field": "entity_id"
+    },
+    { "command": "ha list-services", "tool": "list_services" },
+    { "command": "ha call-service", "tool": "call_service" },
+    {
+      "command": "script run",
+      "tool": "run_script",
+      "positional": "file",
+      "flags": {
+        "cred": { "field": "credentials", "type": "string", "multiple": true }
+      }
+    },
+    {
+      "command": "skill",
+      "effect": "read",
+      "summary": "Print the skills Juno's assistant can load, or one skill's body"
+    },
+    {
+      "command": "ask",
+      "effect": "act",
+      "summary": "Prompt Juno's in-app assistant"
+    },
+    {
+      "command": "session approve",
+      "effect": "act",
+      "summary": "Approve the tool call an assistant session is waiting on"
+    },
+    {
+      "command": "credential set",
+      "effect": "act",
+      "summary": "Set a credential's secret, typed at a terminal with echo off"
+    },
+    {
+      "command": "config set",
+      "effect": "local",
+      "summary": "Remember the instance URL in the user config file"
+    },
+    {
+      "command": "agent-skill install",
+      "effect": "local",
+      "summary": "Write Juno's skill for a coding agent and print its permission block"
+    }
+  ]
+}