@junoflow/cli 0.6.0 → 0.10.0

package/src/commands/init.js

@@ -1,10 +1,9 @@
 import { mkdir, writeFile, access } from 'node:fs/promises';
 import { dirname, join, resolve, sep } from 'node:path';
 
-import { clientName, JunoClient } from '../api.js';
+import { connect } from '../api.js';
 import { printAuthoringIndex } from '../authoring-skills.js';
 import { UsageError, UserError } from '../errors.js';
-import { resolveTarget } from '../target.js';
 
 export const INIT_USAGE = 'juno integration init <id> [--name <name>] [--here]';
 
@@ -29,13 +28,7 @@ export async function init(argv, io) {
     throw new UserError(`${dir} already exists`);
   }
 
-  const target = await resolveTarget({
-    url: argv.url,
-    cwd: io.cwd,
-    env: io.env,
-  });
-  const client =
-    argv.client ?? new JunoClient(target, { client: clientName(io.env) });
+  const { target, client } = await connect(argv, io);
   // The id is validated server-side, against the same rules an install is:
   // one answer to "is this a valid integration id" rather than two.
   const files = await client.scaffold(id, { name: argv.name, target });

package/src/commands/pull.js

@@ -1,143 +1,130 @@
-import { execFile } from 'node:child_process';
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
-import { promisify } from 'node:util';
-
-import { clientName, JunoClient } from '../api.js';
+import { connect } from '../api.js';
 import { UserError } from '../errors.js';
-import { readManifest } from '../project.js';
-import { resolveTarget } from '../target.js';
-
-const execFileAsync = promisify(execFile);
+import {
+  readIntegrationBaseVersion,
+  readManifest,
+  updateIntegrationPackage,
+} from '../project.js';
+import { stampTypeFiles } from '../stamp.js';
+import {
+  baseArtifactPaths,
+  MANIFEST,
+  manifestText,
+  pullArtifacts,
+  requireCleanTree,
+  setDependencies,
+  writeChangedFiles,
+} from '../working-copy.js';
+import { pickTypeFiles } from './gen-types.js';
 
 export const PULL_USAGE = 'juno integration pull [--force] [--id <id>]';
 
 /**
- * `juno integration pull` — write back the manifest and sources Juno holds,
- * and package.json's `scripts`.
+ * `juno integration pull` — make the working copy's artifact files the
+ * install's active version: manifest.json and every file under src/ and
+ * test/, exactly as the version stores them, plus types/ regenerated and
+ * stamped against the pulled manifest, and package.json's
+ * `juno.base_version` (the version pulled, which the next check and deploy
+ * send).
  *
  * This exists because the zip is a good first touch and a bad second one: once
  * the authoring agent has edited an integration you deployed, downloading the
  * project again would clobber your working tree, while pull touches only the
- * things Juno owns. The script lines are among them — the server generates
- * them (POST /api/integrations/scaffold renders this install's project), so a
- * project made by an older CLI picks up the current commands; every other key
- * in package.json is the author's and stays. It still refuses a dirty tree
- * without --force, because an uncommitted edit is the one thing git cannot get
- * back for you.
+ * files Juno stores. The scaffold's script lines are not among them: they are
+ * project content, and an author's own edits to them are theirs — a fresh
+ * `juno integration init` is how to get the current ones. `dependencies` is
+ * replaced only when the pulled manifest declares some (an agent-authored
+ * integration); otherwise they live in package.json alone, which Juno does not
+ * store, and stay. Every other key in package.json, and of `juno`, stays.
+ *
+ * A local file is deleted only when the base version had it and the pulled
+ * one does not; a file neither has is one not deployed yet, and stays. It
+ * still refuses a dirty tree without --force, because an uncommitted edit is
+ * the one thing git cannot get back for you.
  */
 export async function pull(argv, io) {
-  const target = await resolveTarget({
-    url: argv.url,
-    cwd: io.cwd,
-    env: io.env,
-  });
-  const id = argv.id ?? (await readManifest(io.cwd)).id;
+  const { target, client } = await connect(argv, io);
+  let manifestId;
+  try {
+    manifestId = (await readManifest(io.cwd)).id;
+  } catch (err) {
+    // With --id the manifest is about to be replaced, so a broken one is
+    // no reason to refuse.
+    if (argv.id === undefined) throw err;
+  }
+  const id = argv.id ?? manifestId;
   if (!id) {
     throw new UserError(
       'manifest.json declares no id — pass --id <integration>'
     );
   }
 
-  if (!argv.force) {
-    const dirty = await dirtyPaths(io.cwd);
-    if (dirty === null) {
-      io.warn(
-        'not a git repository — pull will overwrite manifest.json, src/ and package.json scripts 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.'
-      );
-    }
-  }
+  await requireCleanTree(io.cwd, {
+    force: argv.force,
+    overwrites: `${MANIFEST}, src/, test/ and types/`,
+    io,
+  });
 
-  const client =
-    argv.client ?? new JunoClient(target, { client: clientName(io.env) });
   const detail = await client.getIntegration(id);
   if (!detail?.manifest) {
     throw new UserError(
       `${id} has no active version on ${target} — nothing to pull`
     );
   }
-  // Fetched before anything is written, so a failure here leaves the working
-  // copy as it was.
-  const scripts = scaffoldScripts(
-    await client.scaffold(id, { target }),
-    target
+  // Everything is fetched before anything is written, so a failure leaves
+  // the working copy as it was.
+  const manifestRaw = manifestText(detail.manifest);
+  const stored = { [MANIFEST]: manifestRaw, ...detail.source_files };
+  const types = stampTypeFiles(
+    pickTypeFiles(await client.typegen(detail.manifest)),
+    manifestRaw
   );
+  // The base belongs to the install the manifest names; pulling another
+  // (--id) has no base to diff against, so it deletes nothing.
+  const base = await baseArtifactPaths({
+    base:
+      id === manifestId ? await readIntegrationBaseVersion(io.cwd) : undefined,
+    version: detail.version,
+    stored,
+    read: async (v) => {
+      const b = await client.getIntegrationVersion(id, v);
+      return b ? [MANIFEST, ...Object.keys(b.SourceFiles ?? {})] : null;
+    },
+    id,
+    target,
+    io,
+  });
 
-  const written = ['manifest.json'];
-  await writeFile(
-    join(io.cwd, 'manifest.json'),
-    `${JSON.stringify(detail.manifest, null, 2)}\n`,
-    'utf8'
+  const { written, removed } = await pullArtifacts(io.cwd, {
+    stored,
+    base,
+    kind: 'integration',
+  });
+  written.push(
+    ...(await writeChangedFiles(
+      io.cwd,
+      Object.fromEntries(
+        Object.entries(types).map(([name, content]) => [
+          `types/${name}`,
+          content,
+        ])
+      )
+    ))
   );
-  for (const [rel, content] of Object.entries(detail.source_files ?? {})) {
-    const path = join(io.cwd, rel);
-    await mkdir(dirname(path), { recursive: true });
-    await writeFile(path, content, 'utf8');
-    written.push(rel);
-  }
-  if (await replaceScripts(io.cwd, scripts, io)) written.push('package.json');
-  io.log(
-    `pulled ${id} v${detail.version} from ${target} (${written.sort().join(', ')})`
+  const wrote = await updateIntegrationPackage(
+    io.cwd,
+    (pkg) => {
+      if (Object.keys(detail.manifest.dependencies ?? {}).length) {
+        setDependencies(pkg, detail.manifest);
+      }
+      pkg.juno.base_version = detail.version;
+    },
+    io
   );
+  if (wrote) written.push('package.json');
   io.log(
-    'run `npm run types` to regenerate types/ against the pulled manifest'
+    `pulled ${id} v${detail.version} from ${target} (${written.sort().join(', ')})`
   );
+  if (removed.length) io.log(`removed ${removed.join(', ')}`);
   return 0;
 }
-
-/** The `scripts` of the package.json a scaffold answered. */
-function scaffoldScripts(files, target) {
-  try {
-    const scripts = JSON.parse(files['package.json']).scripts;
-    if (scripts && typeof scripts === 'object') return scripts;
-  } catch {
-    // Reported below.
-  }
-  throw new UserError(
-    `${target} answered a project with no readable package.json scripts`
-  );
-}
-
-/**
- * replaceScripts sets package.json's `scripts`, keeping every other key and
- * its order, written the way npm writes it. A missing or unreadable
- * package.json is left alone with a warning: pull is not the place to invent
- * one. Returns whether it wrote.
- */
-async function replaceScripts(cwd, scripts, io) {
-  const path = join(cwd, 'package.json');
-  let pkg;
-  try {
-    pkg = JSON.parse(await readFile(path, 'utf8'));
-  } catch {
-    io.warn('no readable package.json — its scripts were not updated');
-    return false;
-  }
-  pkg.scripts = scripts;
-  await writeFile(path, `${JSON.stringify(pkg, null, 2)}\n`, 'utf8');
-  return true;
-}
-
-/**
- * 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;
-  }
-}

package/src/config.js

@@ -1,12 +1,14 @@
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 
 /**
  * The user config file: `$XDG_CONFIG_HOME/juno/config.json`, or
  * `~/.config/juno/config.json` when XDG_CONFIG_HOME is unset. It holds
- * `{"url": "…"}`, the last place resolveTarget looks, and is what makes `juno`
- * usable outside a project after a global install.
+ * `{"url": "…", "token": "juno_…"}`: `url` is the last place resolveTarget
+ * looks, which makes `juno` usable outside a project after a global install,
+ * and `token` is the last place resolveToken looks. The token is a secret,
+ * so the file is mode 0600 (see writeUserConfig).
  */
 export function configPath(env = process.env) {
   const base = env.XDG_CONFIG_HOME || join(env.HOME || homedir(), '.config');
@@ -25,10 +27,23 @@ export async function readUserConfig(env = process.env) {
   }
 }
 
-/** Writes the whole config, creating its directory. */
+/**
+ * Writes the whole config, creating its directory. The file is created 0600,
+ * and one that already exists is narrowed to 0600 before the new content
+ * goes in, so a token never sits in a file other users can read, not even
+ * for the length of one write. (`mode` alone only applies on creation.)
+ */
 export async function writeUserConfig(env = process.env, cfg) {
   const path = configPath(env);
   await mkdir(dirname(path), { recursive: true });
-  await writeFile(path, `${JSON.stringify(cfg, null, 2)}\n`, 'utf8');
+  try {
+    await chmod(path, 0o600);
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+  }
+  await writeFile(path, `${JSON.stringify(cfg, null, 2)}\n`, {
+    encoding: 'utf8',
+    mode: 0o600,
+  });
   return path;
 }

package/src/errors.js

@@ -52,9 +52,9 @@ export class UnreachableError extends Error {
 }
 
 /**
- * ConflictError is a deploy the server refused because the working copy is
- * stale: the flow's active version is not the one `juno.base_version` says it
- * was pulled from (a 409). The top-level handler prints the server's message,
+ * ConflictError is a deploy or check the server refused because the working
+ * copy is stale: the flow's, integration's or app's active version is not the
+ * one `juno.base_version` says it was pulled from (a 409). The top-level handler prints the server's message,
  * which names both versions, and exits 4. The fix is `npm run pull`, or
  * deploying with --force to replace whatever is active.
  */

package/src/exit.js

@@ -8,8 +8,8 @@
  *   2  usage: unknown command or flag, bad --input, a gateway 422 or 404,
  *      a bad --jq
  *   3  the instance is unreachable (the fetch itself failed)
- *   4  a deploy conflict: `juno flow deploy` / `check` against a flow whose
- *      active version is not the working copy's base_version (a 409)
+ *   4  a deploy conflict: a working-copy deploy or check (any kind) got a
+ *      409 because the active version is not the copy's base_version
  *   5  `juno ask` / `session approve`: the turn is still running (pending)
  *   6  `juno ask` / `session approve`: the assistant is awaiting input
  */

package/src/flow-project.js

@@ -1,128 +1,78 @@
-import { readFile, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
-
 import { UserError } from './errors.js';
+import { readSourceFiles, readTestFiles } from './project.js';
+import {
+  baseVersionOf,
+  MANIFEST,
+  manifestText,
+  PACKAGE_JSON,
+  readBoundPackage,
+  readManifestFile,
+  typeFiles,
+  writeChangedFiles,
+  writePackageJSON,
+} from './working-copy.js';
 
 /**
- * A flow working copy is flat (plan-external-agents-flows-as-files.md,
- * Decision 9): manifest.json and flow.ts are the author's, the two .d.ts
- * files are generated, and package.json's `juno` block binds the directory to
- * one flow. The layout is the server's (POST /api/flows/scaffold); this
- * module only knows the handful of names a command reads or writes back.
+ * A flow working copy is laid out as an integration's is: manifest.json, the
+ * sources under src/ (entry src/flow.ts) and the tests under test/ are the
+ * author's, types/ is
+ * generated, and package.json's `juno` block binds the directory to one flow.
+ * The layout is the server's (POST /api/flows/scaffold); this module only
+ * knows the handful of names a command reads or writes back, and what it
+ * shares with an app working copy lives in working-copy.js.
  */
-export const MANIFEST = 'manifest.json';
-export const FLOW_TS = 'flow.ts';
-export const PACKAGE_JSON = 'package.json';
+export { MANIFEST, PACKAGE_JSON, manifestText, typeFiles };
+export const SRC_DIR = 'src';
+export const FLOW_ENTRY = 'src/flow.ts';
 
 /**
  * readFlowProject reads what ingest takes: the manifest (parsed, so a broken
- * one fails here with its parse error rather than as a server 422), flow.ts,
- * and the binding in package.json. `flowId` is `juno.flow_id` — the id is
- * identity, so the CLI sends it and the server refuses a manifest naming
- * another — and `baseVersion` is `juno.base_version`, absent for a flow that
- * has never been deployed from this copy.
+ * one fails here with its parse error rather than as a server 422), every
+ * .ts and .json file under src/ and test/, and the binding in package.json.
+ * Juno stores test/ with the version and never compiles it. A copy
+ * with no src/flow.ts is refused before anything is sent. `flowId` is
+ * `juno.flow_id` — the id is identity, so the CLI sends it and the server
+ * refuses a manifest naming another — and `baseVersion` is
+ * `juno.base_version`, absent for a flow that has never been deployed from
+ * this copy.
  */
 export async function readFlowProject(cwd) {
   const pkg = await readFlowPackage(cwd);
+  const files = await readSourceFiles(cwd);
+  if (!Object.hasOwn(files, FLOW_ENTRY)) {
+    throw new UserError(
+      `no ${FLOW_ENTRY} — a flow working copy's entry is ${FLOW_ENTRY}`
+    );
+  }
   return {
     ...(await readFlowManifest(cwd)),
-    flowTS: await readText(cwd, FLOW_TS),
+    files: { ...files, ...(await readTestFiles(cwd)) },
     packageJSON: pkg,
     flowId: pkg.juno.flow_id,
-    baseVersion: Number.isInteger(pkg.juno.base_version)
-      ? pkg.juno.base_version
-      : undefined,
+    baseVersion: baseVersionOf(pkg),
   };
 }
 
 /** readFlowManifest is manifest.json, as bytes and parsed. */
-export async function readFlowManifest(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}`);
-  }
-}
+export const readFlowManifest = readManifestFile;
 
-/**
- * readFlowPackage is package.json, refusing a directory that is not a flow
- * working copy — 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 flow.ts.
- */
-export async function readFlowPackage(cwd) {
-  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?.flow_id !== 'string' || pkg.juno.flow_id === '') {
-    throw new UserError(
-      `${cwd} is not a flow working copy (no juno.flow_id in package.json) — ` +
-        'run `juno flow init <id>` to make one'
-    );
-  }
-  return pkg;
+/** readFlowPackage is package.json, refusing a directory that is not a flow working copy. */
+export function readFlowPackage(cwd) {
+  return readBoundPackage(cwd, { kind: 'flow', idKey: 'flow_id' });
 }
 
 /**
- * updatePackageJSON rewrites package.json through `mutate`, keeping every key
- * it does not touch (and their order), with a two-space indent and a trailing
- * newline — the way npm writes it, so the diff is only what changed.
+ * updatePackageJSON rewrites a flow working copy's package.json through
+ * `mutate`, keeping every key it does not touch (and their order).
  */
 export async function updatePackageJSON(cwd, mutate) {
   const pkg = await readFlowPackage(cwd);
   mutate(pkg);
-  await writeFile(
-    join(cwd, PACKAGE_JSON),
-    `${JSON.stringify(pkg, null, 2)}\n`,
-    'utf8'
-  );
+  await writePackageJSON(cwd, pkg);
 }
 
 /**
  * writeFlowFiles writes files by working-copy name, skipping one whose
- * content is already what is on disk so a watcher does not see a write that
- * changed nothing. Returns the names it wrote.
+ * content is already what is on disk. Returns the names it wrote.
  */
-export async function writeFlowFiles(cwd, files) {
-  const written = [];
-  for (const [name, content] of Object.entries(files)) {
-    const path = join(cwd, name);
-    let current = null;
-    try {
-      current = await readFile(path, 'utf8');
-    } catch {
-      // Not there yet.
-    }
-    if (current === content) continue;
-    await writeFile(path, content, 'utf8');
-    written.push(name);
-  }
-  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 the two keeps a future third file working without a CLI release.
- */
-export function typeFiles(types) {
-  return Object.fromEntries(
-    Object.entries(types ?? {}).filter(([name]) => name.endsWith('.d.ts'))
-  );
-}
-
-async function readText(cwd, name) {
-  try {
-    return await readFile(join(cwd, name), 'utf8');
-  } catch {
-    throw new UserError(`no ${name} in ${cwd}`);
-  }
-}
+export const writeFlowFiles = writeChangedFiles;