@junoflow/cli 0.1.5 → 0.6.0

package/src/commands/flow-init.js

@@ -0,0 +1,59 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+
+import { connect } from '../api.js';
+import { printAuthoringIndex } from '../authoring-skills.js';
+import { UsageError, UserError } from '../errors.js';
+import { exists, safeRelative } from './init.js';
+
+export const FLOW_INIT_USAGE = 'juno flow init <id> [--here]';
+
+/**
+ * `juno flow init <id>` — a working copy of the flow's active version, or a
+ * stub for an id with none, written into ./<id> (or the current directory
+ * with --here).
+ *
+ * Every file comes from POST /api/flows/scaffold, the single generator of a
+ * flow 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 flow author's skill index, which is where an external agent starts.
+ */
+export async function flowInit(argv, io) {
+  const [id, ...extra] = argv._;
+  if (!id || extra.length > 0) {
+    throw new UsageError(`usage: ${FLOW_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: one answer to "is this a valid flow id".
+  const { files, warnings } = await client.scaffoldFlow(id, { target });
+
+  for (const [rel, content] of Object.entries(files)) {
+    const path = join(dir, safeRelative(rel));
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, content, 'utf8');
+  }
+  printScaffoldWarnings(warnings, io);
+
+  io.log(`created ${dir}`);
+  io.log('');
+  io.log(argv.here ? 'npm install' : `cd ${id} && npm install`);
+  io.log('npm test');
+  io.log('npm run deploy');
+  await printAuthoringIndex('flow', client, target, io);
+  return 0;
+}
+
+/**
+ * A stored manifest the live catalog now refuses (a state it binds was
+ * deleted, say) still scaffolds, because the working copy is how it gets
+ * fixed; the refusal comes along as warnings, and they go to stderr.
+ */
+export function printScaffoldWarnings(warnings, io) {
+  for (const w of warnings ?? []) io.warn(`warning: ${w}`);
+}

package/src/commands/flow-pull.js

@@ -0,0 +1,86 @@
+import { connect } from '../api.js';
+import { UserError } from '../errors.js';
+import {
+  FLOW_TS,
+  MANIFEST,
+  PACKAGE_JSON,
+  readFlowPackage,
+  updatePackageJSON,
+  writeFlowFiles,
+} from '../flow-project.js';
+import { printScaffoldWarnings } from './flow-init.js';
+import { dirtyPaths } from './pull.js';
+
+export const FLOW_PULL_USAGE = 'juno flow pull [--force]';
+
+/**
+ * `juno flow pull` — overwrite the working copy with the flow's active
+ * version: manifest.json, flow.ts and both .d.ts files, plus package.json's
+ * `scripts`, `dependencies` and `juno.base_version` — every other key in
+ * package.json is the author's and stays. Everything comes from
+ * POST /api/flows/scaffold, the same render `init` writes, so a pulled copy
+ * and a fresh one cannot differ.
+ *
+ * It refuses a dirty git tree without --force, as integration pull does: an
+ * uncommitted edit is the one thing nothing can get back.
+ */
+export async function flowPull(argv, io) {
+  const { juno } = await readFlowPackage(io.cwd);
+  const flowId = juno.flow_id;
+
+  if (!argv.force) {
+    const dirty = await dirtyPaths(io.cwd);
+    if (dirty === null) {
+      io.warn(
+        `not a git repository — pull will overwrite ${MANIFEST} and ${FLOW_TS} 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.'
+      );
+    }
+  }
+
+  const { target, client } = await connect(argv, io);
+  const { files, warnings } = await client.scaffoldFlow(flowId, { 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;
+  // No base_version is the scaffold's stub for a flow with no active
+  // version; writing it over the author's work would lose it for nothing.
+  if (!Number.isInteger(version)) {
+    throw new UserError(
+      `${flowId} has no active version on ${target} — nothing to pull`
+    );
+  }
+
+  const written = await writeFlowFiles(
+    io.cwd,
+    Object.fromEntries(
+      Object.entries(files).filter(
+        ([name]) =>
+          name === MANIFEST || name === FLOW_TS || name.endsWith('.d.ts')
+      )
+    )
+  );
+  await updatePackageJSON(io.cwd, (pkg) => {
+    pkg.scripts = scaffoldPkg.scripts;
+    if (scaffoldPkg.dependencies) pkg.dependencies = scaffoldPkg.dependencies;
+    else delete pkg.dependencies;
+    pkg.juno.base_version = version;
+  });
+  written.push(PACKAGE_JSON);
+  printScaffoldWarnings(warnings, io);
+
+  io.log(
+    `pulled ${flowId} v${version} from ${target} (${written.sort().join(', ')})`
+  );
+  return 0;
+}

package/src/commands/{types.js → gen-types.js}

@@ -1,21 +1,28 @@
-import { JunoClient } from '../api.js';
+import { clientName, JunoClient } from '../api.js';
 import { readManifest, readManifestRaw, writeTypes } from '../project.js';
 import { stampTypeFiles } from '../stamp.js';
 import { resolveTarget } from '../target.js';
 
+export const GEN_TYPES_USAGE = 'juno integration gen-types';
+
 /**
- * `juno types` — POST manifest.json, write back types/.
+ * `juno integration gen-types` — POST manifest.json, write back types/.
  *
  * Both halves come from one call so they cannot skew, and they are committed:
  * a fresh clone compiles offline, and a contributor fixing a bug in someone
  * else's integration never needs a Juno instance. Only the person editing the
  * manifest does, which is the right person to require it of.
  */
-export async function types(argv, io) {
-  const target = await resolveTarget({ url: argv.url, cwd: io.cwd });
+export async function genTypes(argv, io) {
+  const target = await resolveTarget({
+    url: argv.url,
+    cwd: io.cwd,
+    env: io.env,
+  });
   const raw = await readManifestRaw(io.cwd);
   const manifest = await readManifest(io.cwd);
-  const client = argv.client ?? new JunoClient(target);
+  const client =
+    argv.client ?? new JunoClient(target, { client: clientName(io.env) });
 
   const generated = await client.typegen(manifest);
   const written = await writeTypes(

package/src/commands/init.js

@@ -1,33 +1,44 @@
 import { mkdir, writeFile, access } from 'node:fs/promises';
 import { dirname, join, resolve, sep } from 'node:path';
 
-import { JunoClient } from '../api.js';
-import { UserError } from '../errors.js';
+import { clientName, JunoClient } 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]';
+
 /**
- * `juno init [name]` — ask a Juno for a starting project and write it down.
+ * `juno integration init <id>` — a working copy of the install's active
+ * version, or a starting project for an id with none, written into ./<id>
+ * (or the current directory with --here).
  *
  * Every file comes from `POST /api/integrations/scaffold`, which renders it
  * with the same generator behind **Develop locally → Download project**. The
  * CLI holds no copy of the layout: a scaffold and an ejected project cannot
- * drift, and the starter arrives with `types/` already generated, which only
- * the server can produce.
+ * drift, and the project arrives with `types/` already generated, which only
+ * the server can produce. `--name` shapes only a starter. After the next steps
+ * it prints the integration author's skill index.
  */
 export async function init(argv, io) {
-  const name = argv._[0] ?? argv.name;
-  if (!name) throw new UserError('usage: juno init <name>');
+  const [id, ...extra] = argv._;
+  if (!id || extra.length > 0) throw new UsageError(`usage: ${INIT_USAGE}`);
 
-  const dir = resolve(io.cwd, argv.here ? '.' : name);
+  const dir = resolve(io.cwd, argv.here ? '.' : id);
   if (!argv.here && (await exists(dir))) {
     throw new UserError(`${dir} already exists`);
   }
 
-  const target = await resolveTarget({ url: argv.url, cwd: io.cwd });
-  const client = argv.client ?? new JunoClient(target);
-  // The name is validated server-side, against the same rules an install is:
-  // one answer to "is this a valid integration name" rather than two.
-  const files = await client.scaffold(name, { target });
+  const target = await resolveTarget({
+    url: argv.url,
+    cwd: io.cwd,
+    env: io.env,
+  });
+  const client =
+    argv.client ?? new JunoClient(target, { client: clientName(io.env) });
+  // 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 });
 
   for (const [rel, content] of Object.entries(files)) {
     const path = join(dir, safeRelative(rel));
@@ -37,9 +48,10 @@ export async function init(argv, io) {
 
   io.log(`created ${dir}`);
   io.log('');
-  io.log(argv.here ? 'npm install' : `cd ${name} && npm install`);
+  io.log(argv.here ? 'npm install' : `cd ${id} && npm install`);
   io.log('npm test');
   io.log('npm run deploy');
+  await printAuthoringIndex('integration', client, target, io);
   return 0;
 }
 
@@ -48,7 +60,7 @@ export async function init(argv, io) {
  * but "write these paths" is the one place a bad answer escapes the project
  * directory, and checking costs a line.
  */
-function safeRelative(rel) {
+export function safeRelative(rel) {
   const parts = rel.split('/');
   if (rel.startsWith('/') || parts.includes('..') || parts.includes('')) {
     throw new UserError(
@@ -58,7 +70,7 @@ function safeRelative(rel) {
   return parts.join(sep);
 }
 
-async function exists(path) {
+export async function exists(path) {
   try {
     await access(path);
     return true;

package/src/commands/pull.js

@@ -1,30 +1,41 @@
 import { execFile } from 'node:child_process';
-import { mkdir, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { promisify } from 'node:util';
 
-import { JunoClient } from '../api.js';
+import { clientName, JunoClient } from '../api.js';
 import { UserError } from '../errors.js';
 import { readManifest } from '../project.js';
 import { resolveTarget } from '../target.js';
 
 const execFileAsync = promisify(execFile);
 
+export const PULL_USAGE = 'juno integration pull [--force] [--id <id>]';
+
 /**
- * `juno pull` — write back the manifest and sources Juno holds.
+ * `juno integration pull` — write back the manifest and sources Juno holds,
+ * and package.json's `scripts`.
  *
  * 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
- * two things Juno owns. It still refuses a dirty tree without --force, because
- * an uncommitted edit is the one thing git cannot get back for you.
+ * 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.
  */
 export async function pull(argv, io) {
-  const target = await resolveTarget({ url: argv.url, cwd: io.cwd });
-  const name = argv.name ?? (await readManifest(io.cwd)).name;
-  if (!name) {
+  const target = await resolveTarget({
+    url: argv.url,
+    cwd: io.cwd,
+    env: io.env,
+  });
+  const id = argv.id ?? (await readManifest(io.cwd)).id;
+  if (!id) {
     throw new UserError(
-      'manifest.json declares no name — pass --name <integration>'
+      'manifest.json declares no id — pass --id <integration>'
     );
   }
 
@@ -32,7 +43,7 @@ export async function pull(argv, io) {
     const dirty = await dirtyPaths(io.cwd);
     if (dirty === null) {
       io.warn(
-        'not a git repository — pull will overwrite manifest.json and src/ with no undo'
+        '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(
@@ -42,13 +53,20 @@ export async function pull(argv, io) {
     }
   }
 
-  const client = argv.client ?? new JunoClient(target);
-  const detail = await client.getIntegration(name);
+  const client =
+    argv.client ?? new JunoClient(target, { client: clientName(io.env) });
+  const detail = await client.getIntegration(id);
   if (!detail?.manifest) {
     throw new UserError(
-      `${name} has no active version on ${target} — nothing to pull`
+      `${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
+  );
 
   const written = ['manifest.json'];
   await writeFile(
@@ -62,19 +80,55 @@ export async function pull(argv, io) {
     await writeFile(path, content, 'utf8');
     written.push(rel);
   }
+  if (await replaceScripts(io.cwd, scripts, io)) written.push('package.json');
   io.log(
-    `pulled ${name} v${detail.version} from ${target} (${written.sort().join(', ')})`
+    `pulled ${id} v${detail.version} from ${target} (${written.sort().join(', ')})`
+  );
+  io.log(
+    'run `npm run types` to regenerate types/ against the pulled manifest'
   );
-  io.log('run `juno types` to regenerate types/ against the pulled manifest');
   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.
  */
-async function dirtyPaths(cwd) {
+export async function dirtyPaths(cwd) {
   try {
     const { stdout } = await execFileAsync('git', ['status', '--porcelain'], {
       cwd,

package/src/commands/session-approve.js

@@ -0,0 +1,73 @@
+import { randomUUID } from 'node:crypto';
+
+import { connect } from '../api.js';
+import { UsageError, UserError } from '../errors.js';
+import { converse, finish } from '../prompt.js';
+import { waitSeconds } from './ask.js';
+
+export const SESSION_APPROVE_USAGE =
+  'juno session approve <session-id> [--wait <seconds>]';
+
+/**
+ * `juno session approve <id>` lets through the tool call an assistant session
+ * is waiting on. It is its own command, not `juno ask … approve`, so that a
+ * permission rule allowing `juno ask` does not also let a coding agent
+ * approve the assistant's call_service on the user's behalf.
+ *
+ * It checks first that the session is awaiting an approval — anything else
+ * sent to a question would be taken as the answer — then sends `approve` as
+ * `juno ask` would, and prints and exits the same way.
+ */
+export async function sessionApprove(args, io) {
+  const [id, ...extra] = args._;
+  if (id === undefined || extra.length) {
+    throw new UsageError(`usage: ${SESSION_APPROVE_USAGE}`);
+  }
+  const wait = waitSeconds(args.wait);
+
+  const { client } = await connect(args, io);
+  const session = await client.getAgentSession(id);
+  if (!session) throw new UserError(`no assistant session ${id}`);
+  const refusal = notAwaitingApproval(session, id);
+  if (refusal) throw new UserError(refusal);
+
+  const body = {
+    session_id: id,
+    message: 'approve',
+    message_id: randomUUID(),
+    wait_timeout_seconds: wait,
+  };
+  // Never resent after a busy 409: whatever is pending by then is not what
+  // was checked above.
+  const outcome = await converse(client, body, {
+    stream: false,
+    io,
+    resendWhenBusy: false,
+  });
+  return finish(outcome, id, io);
+}
+
+/** What the session is doing instead of waiting on an approval, if it is. */
+function notAwaitingApproval(session, id) {
+  const pending = session.pending_input;
+  if (session.status === 'awaiting_input' && pending?.kind === 'approval') {
+    return null;
+  }
+  if (session.status === 'awaiting_input') {
+    return (
+      `session ${id} is asking a question, not waiting for an approval: ` +
+      `${JSON.stringify(pending?.question ?? '')}\n` +
+      `answer it with: juno ask --session ${id} "<answer>"`
+    );
+  }
+  if (session.status === 'active') {
+    return (
+      `session ${id} is running a turn and has nothing to approve yet; ` +
+      `wait for it with: juno ask --session ${id}`
+    );
+  }
+  if (session.status === 'idle') {
+    return `session ${id} is idle and has nothing to approve`;
+  }
+  return `session ${id} has ended (status: ${session.status}); there is nothing to approve`;
+}

package/src/commands/skill.js

@@ -0,0 +1,73 @@
+import { connect } from '../api.js';
+import { UsageError } from '../errors.js';
+import { warnIfStale } from '../installed-skill.js';
+import { levenshtein } from '../suggest.js';
+
+export const SKILL_USAGE = 'juno skill [<name>] [--json]';
+
+/**
+ * `juno skill` prints the skills the instance serves: with no name, one line
+ * per skill; with a name, that skill's body exactly as served. `--json`
+ * prints the route's JSON instead. The server renders each tool reference as
+ * the `juno` command in front of it; the CLI does not rewrite them. The index
+ * also says when an installed agent skill is older than what the instance
+ * serves (installed-skill.js).
+ */
+export async function skill(args, io) {
+  const [name, ...extra] = args._;
+  if (extra.length) throw new UsageError(`usage: ${SKILL_USAGE}`);
+
+  const { target, client } = await connect(args, io);
+
+  if (name === undefined) {
+    const index = await client.listSkills();
+    await warnIfStale(index, target, io);
+    if (args.json) return printJSON(index, io);
+    for (const s of index?.skills ?? []) {
+      io.log(`${s.name} — ${s.description}`);
+    }
+    return 0;
+  }
+
+  const detail = await client.getSkill(name);
+  if (!detail) {
+    const { skills = [] } = (await client.listSkills()) ?? {};
+    throw unknownSkill(
+      name,
+      skills.map((s) => s.name)
+    );
+  }
+  if (args.json) return printJSON(detail, io);
+  // Verbatim: the body's own trailing newline is the last byte written.
+  io.write(detail.body);
+  return 0;
+}
+
+/** Compact off a TTY, indented on one, as every JSON the CLI prints. */
+function printJSON(value, io) {
+  io.log(io.isTTY ? JSON.stringify(value, null, 2) : JSON.stringify(value));
+  return 0;
+}
+
+/**
+ * unknownSkill names up to three served skills near what was typed. Skill
+ * names are short, so the distance allowed grows with the name, and a name
+ * that contains what was typed (`integration` → `integration-states`) counts
+ * as near.
+ */
+function unknownSkill(name, names) {
+  const max = Math.max(3, Math.floor(name.length / 2));
+  const near = names
+    .map((n) => ({
+      n,
+      d: n.includes(name) ? 0 : levenshtein(name, n),
+    }))
+    .filter(({ d }) => d <= max)
+    .sort((a, b) => a.d - b.d)
+    .slice(0, 3)
+    .map(({ n }) => `"${n}"`);
+  const hint = near.length
+    ? `did you mean ${near.join(', ')}?`
+    : 'run `juno skill` for the list';
+  return new UsageError(`unknown skill "${name}"; ${hint}`);
+}