@junoflow/cli 0.15.0 → 0.17.0

package/verbs.json

@@ -1,8 +1,33 @@
 {
+  "groups": {
+    "state": "States: named values, most decided by a layer stack of rules, claims and bindings",
+    "flow": "Flows: TypeScript automations started by events, schedules, webhooks or calls; authored as a working copy",
+    "run": "A flow's runs: what each one did and how it ended",
+    "timer": "Upcoming timers: every flow schedule, soonest first",
+    "activity": "The run timeline across every flow",
+    "integration": "Integrations: installed TypeScript that talks to an outside service; authored as a working copy",
+    "device": "Devices: follow states and write them to one endpoint (a Home Assistant entity, an MQTT topic)",
+    "control": "Controls: buttons, switches and selects a person presses",
+    "app": "Apps: small web pages for people, backed by Juno; authored as a working copy",
+    "finding": "Findings: standing facts flows, integrations and tasks assert (\"freezer too warm\")",
+    "webhook": "Webhooks: URLs that start flows",
+    "task": "Tasks: jobs that report to a ping URL, chores a person is reminded of, work a flow opens",
+    "series": "Series: values over time an integration publishes (a forecast, a price list)",
+    "credential": "Credentials: the secrets flows and integrations use, by id; only the user sets a value",
+    "person": "People and their contacts: who Juno notifies and asks",
+    "question": "Questions flows ask people, and the answers",
+    "approval": "Destructive commands waiting for a person to approve them in Juno",
+    "ha": "Home Assistant: entities, their history, services",
+    "mqtt": "MQTT: the topics seen and the broker connection",
+    "script": "Run an exploratory TypeScript script in Juno's sandbox",
+    "session": "Conversations with Juno's own assistant (juno ask)",
+    "config": "This machine's CLI settings: the instance URL and the API key"
+  },
   "commands": [
     {
       "command": "discover",
       "tool": "discover",
+      "summary": "Search everything in Juno by what the user calls it; every hit carries a kind and an id",
       "id_field": "query",
       "flags": {
         "kind": { "field": "kinds", "type": "string", "multiple": true }
@@ -12,6 +37,7 @@
     {
       "command": "related",
       "tool": "get_related",
+      "summary": "Walk the reference graph from one thing: what it uses and what uses it",
       "positional": "kind:id",
       "flags": { "degree": { "field": "degree", "type": "integer" } },
       "naming_exception": "takes any kind, so it has no group"
@@ -27,6 +53,11 @@
       "tool": "get_state_layers",
       "id_field": "id"
     },
+    {
+      "command": "state list-layer-versions",
+      "tool": "list_state_layer_versions",
+      "id_field": "id"
+    },
     { "command": "state evaluate-level", "tool": "evaluate_level" },
     {
       "command": "state preview-layers",
@@ -43,6 +74,12 @@
       "id_field": "id",
       "fixed_input": { "dry_run": false }
     },
+    {
+      "command": "state restore-layers",
+      "tool": "restore_state_layers",
+      "id_field": "id",
+      "flags": { "version": { "field": "version", "type": "integer" } }
+    },
     {
       "command": "state set-value",
       "tool": "set_state_value",
@@ -50,12 +87,39 @@
     },
     { "command": "state claim", "tool": "claim_state", "id_field": "id" },
     { "command": "state release", "tool": "release_state", "id_field": "id" },
+    { "command": "state delete", "tool": "delete_state", "id_field": "id" },
     { "command": "flow get", "tool": "get_flow", "id_field": "id" },
+    {
+      "command": "flow list-versions",
+      "tool": "list_flow_versions",
+      "id_field": "id"
+    },
+    {
+      "command": "flow get-next-fire",
+      "tool": "get_next_fire",
+      "id_field": "flow_id",
+      "flags": { "trigger": { "field": "trigger", "type": "string" } }
+    },
+    {
+      "command": "flow restore-version",
+      "tool": "restore_flow_version",
+      "id_field": "id",
+      "flags": { "version": { "field": "version", "type": "integer" } }
+    },
     {
       "command": "flow set-enabled",
       "tool": "set_flow_enabled",
       "id_field": "flow_id"
     },
+    {
+      "command": "flow rename",
+      "tool": "rename_flow",
+      "id_field": "id",
+      "flags": {
+        "name": { "field": "name", "type": "string" },
+        "slug": { "field": "slug", "type": "string" }
+      }
+    },
     {
       "command": "flow trigger",
       "tool": "trigger_flow",
@@ -66,6 +130,7 @@
       "tool": "fire_trigger",
       "id_field": "flow_id"
     },
+    { "command": "flow delete", "tool": "delete_flow", "id_field": "id" },
     {
       "command": "flow init",
       "effect": "read",
@@ -104,22 +169,93 @@
     },
     { "command": "run list", "tool": "list_runs" },
     { "command": "run get", "tool": "get_run", "id_field": "run_id" },
+    { "command": "timer list", "tool": "list_timers" },
+    {
+      "command": "activity list",
+      "tool": "list_activity",
+      "flags": {
+        "hours": { "field": "hours", "type": "integer" },
+        "flow": { "field": "flow_id", "type": "string" },
+        "limit": { "field": "limit", "type": "integer" }
+      }
+    },
     {
       "command": "integration get",
       "tool": "get_integration",
       "id_field": "id"
     },
+    {
+      "command": "integration list-versions",
+      "tool": "list_integration_versions",
+      "id_field": "id"
+    },
+    { "command": "integration preview", "tool": "preview_integration" },
+    {
+      "command": "integration list-invocations",
+      "tool": "list_integration_invocations",
+      "id_field": "id",
+      "flags": { "limit": { "field": "limit", "type": "integer" } }
+    },
+    {
+      "command": "integration get-deliveries",
+      "tool": "get_integration_deliveries",
+      "id_field": "id",
+      "flags": { "limit": { "field": "limit", "type": "integer" } }
+    },
+    {
+      "command": "integration get-usage",
+      "tool": "get_integration_usage",
+      "id_field": "id"
+    },
+    { "command": "integration list-registry", "tool": "list_registry" },
     {
       "command": "integration configure",
       "tool": "configure_integration",
       "id_field": "id"
     },
+    {
+      "command": "integration restore-version",
+      "tool": "restore_integration_version",
+      "id_field": "id",
+      "flags": { "version": { "field": "version", "type": "integer" } }
+    },
+    {
+      "command": "integration set-enabled",
+      "tool": "set_integration_enabled",
+      "id_field": "id"
+    },
+    {
+      "command": "integration bind-webhook",
+      "tool": "bind_integration_webhook",
+      "id_field": "id",
+      "flags": {
+        "slot": { "field": "slot", "type": "string" },
+        "webhook": { "field": "webhook", "type": "string" }
+      }
+    },
     { "command": "integration install", "tool": "install_integration" },
+    {
+      "command": "integration invoke-action",
+      "tool": "invoke_integration_action",
+      "id_field": "id",
+      "flags": { "action": { "field": "action", "type": "string" } }
+    },
     {
       "command": "integration run-schedule",
       "tool": "run_integration_schedule",
       "id_field": "integration"
     },
+    {
+      "command": "integration upgrade",
+      "tool": "upgrade_integration",
+      "id_field": "id",
+      "flags": { "ref": { "field": "ref", "type": "string" } }
+    },
+    {
+      "command": "integration uninstall",
+      "tool": "uninstall_integration",
+      "id_field": "id"
+    },
     {
       "command": "integration init",
       "effect": "read",
@@ -158,17 +294,59 @@
     },
     { "command": "device list", "tool": "list_devices" },
     { "command": "device get", "tool": "get_device", "id_field": "id" },
+    {
+      "command": "device list-versions",
+      "tool": "list_device_versions",
+      "id_field": "id"
+    },
     { "command": "device preview", "tool": "preview_device" },
     { "command": "device write", "tool": "write_device" },
+    {
+      "command": "device restore-version",
+      "tool": "restore_device_version",
+      "id_field": "id",
+      "flags": { "version": { "field": "version", "type": "integer" } }
+    },
     { "command": "device suspend", "tool": "suspend_device", "id_field": "id" },
     { "command": "device release", "tool": "release_device", "id_field": "id" },
+    { "command": "device delete", "tool": "delete_device", "id_field": "id" },
+    { "command": "control get", "tool": "get_control", "id_field": "id" },
+    { "command": "control list", "tool": "list_controls" },
+    {
+      "command": "control get-history",
+      "tool": "get_control_history",
+      "id_field": "id"
+    },
+    {
+      "command": "control get-activity",
+      "tool": "get_control_activity",
+      "id_field": "id",
+      "flags": { "limit": { "field": "limit", "type": "integer" } }
+    },
+    {
+      "command": "control list-versions",
+      "tool": "list_control_versions",
+      "id_field": "id"
+    },
     { "command": "control write", "tool": "write_control" },
+    {
+      "command": "control restore-version",
+      "tool": "restore_control_version",
+      "id_field": "id",
+      "flags": { "version": { "field": "version", "type": "integer" } }
+    },
     { "command": "control use", "tool": "use_control", "id_field": "id" },
+    {
+      "command": "control extend",
+      "tool": "extend_control",
+      "id_field": "id"
+    },
     {
       "command": "control release",
       "tool": "release_control",
       "id_field": "id"
     },
+    { "command": "control delete", "tool": "delete_control", "id_field": "id" },
     { "command": "app get", "tool": "get_app", "id_field": "id" },
     {
       "command": "app list-invocations",
@@ -176,6 +354,39 @@
       "id_field": "id",
       "flags": { "limit": { "field": "limit", "type": "integer" } }
     },
+    {
+      "command": "app list-versions",
+      "tool": "list_app_versions",
+      "id_field": "id"
+    },
+    { "command": "app list-links", "tool": "list_app_links", "id_field": "id" },
+    {
+      "command": "app restore-version",
+      "tool": "restore_app_version",
+      "id_field": "id",
+      "flags": { "version": { "field": "version", "type": "integer" } }
+    },
+    {
+      "command": "app set-enabled",
+      "tool": "set_app_enabled",
+      "id_field": "id"
+    },
+    {
+      "command": "app create-link",
+      "tool": "create_app_link",
+      "id_field": "id",
+      "flags": {
+        "name": { "field": "name", "type": "string" },
+        "expires-at": { "field": "expires_at", "type": "string" }
+      }
+    },
+    {
+      "command": "app revoke-link",
+      "tool": "revoke_app_link",
+      "id_field": "id",
+      "flags": { "link": { "field": "link", "type": "string" } }
+    },
+    { "command": "app delete", "tool": "delete_app", "id_field": "id" },
     {
       "command": "app init",
       "effect": "read",
@@ -246,16 +457,125 @@
     },
     { "command": "webhook write", "tool": "write_webhook", "id_field": "id" },
     { "command": "webhook fire", "tool": "fire_webhook", "id_field": "id" },
+    { "command": "webhook delete", "tool": "delete_webhook", "id_field": "id" },
+    {
+      "command": "webhook rotate-token",
+      "tool": "rotate_webhook_token",
+      "id_field": "id"
+    },
     { "command": "task list", "tool": "list_tasks" },
     { "command": "task get-runs", "tool": "get_task_runs", "id_field": "id" },
+    {
+      "command": "task get-occurrence",
+      "tool": "get_task_occurrence",
+      "id_field": "id",
+      "flags": { "key": { "field": "key", "type": "string" } }
+    },
+    {
+      "command": "task inbox",
+      "tool": "list_task_inbox",
+      "naming_exception": "the inbox's To do list is what a person calls it; list-inbox reads as a list of inboxes"
+    },
     { "command": "task write", "tool": "write_task", "id_field": "id" },
     { "command": "task delete", "tool": "delete_task", "id_field": "id" },
-    { "command": "task command", "tool": "command_task", "id_field": "id" },
+    {
+      "command": "task rotate-token",
+      "tool": "rotate_task_token",
+      "id_field": "id"
+    },
+    {
+      "command": "task open",
+      "tool": "command_task",
+      "id_field": "id",
+      "flags": {
+        "key": { "field": "key", "type": "string" },
+        "at": { "field": "at", "type": "string" },
+        "within": { "field": "within", "type": "string" },
+        "reason": { "field": "reason", "type": "string" }
+      },
+      "fixed_input": { "verb": "open" },
+      "summary": "Open a piece of work, due at --at (now) and overdue --within after",
+      "naming_exception": "one command per verb of command_task, which the row fixes"
+    },
+    {
+      "command": "task snooze",
+      "tool": "command_task",
+      "id_field": "id",
+      "flags": {
+        "key": { "field": "key", "type": "string" },
+        "until": { "field": "until", "type": "string" }
+      },
+      "fixed_input": { "verb": "snooze" },
+      "summary": "Move a piece of work's due date later, to --until",
+      "naming_exception": "one command per verb of command_task, which the row fixes"
+    },
+    {
+      "command": "task set-due",
+      "tool": "command_task",
+      "id_field": "id",
+      "flags": {
+        "key": { "field": "key", "type": "string" },
+        "at": { "field": "at", "type": "string" }
+      },
+      "fixed_input": { "verb": "set-due" },
+      "summary": "Set a piece of work's due date, earlier or later, to --at",
+      "naming_exception": "one command per verb of command_task, which the row fixes"
+    },
+    {
+      "command": "task complete",
+      "tool": "command_task",
+      "id_field": "id",
+      "flags": {
+        "key": { "field": "key", "type": "string" },
+        "outcome": { "field": "outcome", "type": "string" },
+        "note": { "field": "note", "type": "string" },
+        "check": { "field": "check", "type": "integer", "multiple": true }
+      },
+      "fixed_input": { "verb": "complete" },
+      "summary": "Mark a piece of work done; --check ticks checklist items by number",
+      "naming_exception": "one command per verb of command_task, which the row fixes"
+    },
+    {
+      "command": "task skip",
+      "tool": "command_task",
+      "id_field": "id",
+      "flags": {
+        "key": { "field": "key", "type": "string" },
+        "note": { "field": "note", "type": "string" }
+      },
+      "fixed_input": { "verb": "skip" },
+      "summary": "Close a manual task's work as not being done, opening its skipped finding",
+      "naming_exception": "one command per verb of command_task, which the row fixes"
+    },
+    {
+      "command": "task cancel",
+      "tool": "command_task",
+      "id_field": "id",
+      "flags": {
+        "key": { "field": "key", "type": "string" },
+        "reason": { "field": "reason", "type": "string" }
+      },
+      "fixed_input": { "verb": "cancel" },
+      "summary": "Close a piece of work that is no longer needed, with no run and no finding",
+      "naming_exception": "one command per verb of command_task, which the row fixes"
+    },
     { "command": "series get", "tool": "get_series", "id_field": "id" },
     { "command": "credential list", "tool": "list_credentials" },
+    {
+      "command": "credential delete",
+      "tool": "delete_credential",
+      "id_field": "id"
+    },
     { "command": "person list", "tool": "list_people" },
     { "command": "person get", "tool": "get_person", "id_field": "id" },
     { "command": "person write", "tool": "write_person", "id_field": "id" },
+    {
+      "command": "person test-contact",
+      "tool": "test_contact",
+      "id_field": "id",
+      "flags": { "contact": { "field": "contact", "type": "string" } }
+    },
+    { "command": "person delete", "tool": "delete_person", "id_field": "id" },
     {
       "command": "question list",
       "tool": "list_questions",
@@ -277,6 +597,12 @@
         "for": { "field": "for", "type": "string" }
       }
     },
+    {
+      "command": "approval list",
+      "tool": "list_approvals",
+      "flags": { "status": { "field": "status", "type": "string" } }
+    },
+    { "command": "approval get", "tool": "get_approval", "id_field": "id" },
     {
       "command": "ha get-entity",
       "tool": "get_entity",
@@ -288,7 +614,26 @@
       "id_field": "entity_id"
     },
     { "command": "ha list-services", "tool": "list_services" },
+    {
+      "command": "ha list-entities",
+      "tool": "list_entities",
+      "flags": {
+        "query": { "field": "query", "type": "string" },
+        "limit": { "field": "limit", "type": "integer" }
+      }
+    },
+    { "command": "ha get-diagnostics", "tool": "get_ha_diagnostics" },
     { "command": "ha call-service", "tool": "call_service" },
+    {
+      "command": "mqtt list-topics",
+      "tool": "list_topics",
+      "flags": {
+        "query": { "field": "query", "type": "string" },
+        "sort": { "field": "sort", "type": "string" },
+        "limit": { "field": "limit", "type": "integer" }
+      }
+    },
+    { "command": "mqtt get-diagnostics", "tool": "get_mqtt_diagnostics" },
     {
       "command": "script run",
       "tool": "run_script",
@@ -307,11 +652,56 @@
       "effect": "act",
       "summary": "Prompt Juno's in-app assistant"
     },
+    {
+      "command": "whoami",
+      "effect": "read",
+      "summary": "Print who the instance takes you for: the principal, its scope and the linked person"
+    },
+    {
+      "command": "version",
+      "effect": "read",
+      "summary": "Print the instance's version, build time and schema version, and this CLI's version"
+    },
+    {
+      "command": "permissions",
+      "effect": "read",
+      "summary": "Print Claude Code permission rules that allow the read (and optionally change) commands"
+    },
+    {
+      "command": "session list",
+      "effect": "read",
+      "summary": "List assistant sessions, newest first"
+    },
+    {
+      "command": "session get",
+      "effect": "read",
+      "summary": "Print an assistant session: its status, what it waits on, and with --transcript its transcript"
+    },
+    {
+      "command": "session export",
+      "effect": "read",
+      "summary": "Print an assistant session's full export, transcript and tool calls included"
+    },
+    {
+      "command": "session rate",
+      "effect": "change",
+      "summary": "Rate an assistant session: up, down, addressed (a thumbs down whose cause is fixed) or none"
+    },
     {
       "command": "session approve",
       "effect": "act",
       "summary": "Approve the tool call an assistant session is waiting on"
     },
+    {
+      "command": "session cancel",
+      "effect": "act",
+      "summary": "Cancel an assistant session that is running or waiting"
+    },
+    {
+      "command": "approval wait",
+      "effect": "read",
+      "summary": "Wait for a person to decide an approval, then print how it ended"
+    },
     {
       "command": "task run",
       "effect": "act",
@@ -331,11 +721,6 @@
       "command": "config set",
       "effect": "local",
       "summary": "Remember the instance URL or the API key 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"
     }
   ]
 }

package/src/commands/agent-skill-install.js

@@ -1,64 +0,0 @@
-import { mkdir, writeFile } from 'node:fs/promises';
-import { join, resolve } from 'node:path';
-
-import { connect } from '../api.js';
-import { UsageError } from '../errors.js';
-import { SKILL_DIR } from '../installed-skill.js';
-
-export const AGENT_SKILL_INSTALL_USAGE =
-  'juno agent-skill install [--dir <path>] [--allow-change] [--working-copy] [--agents-md] [--json]';
-
-/**
- * `juno agent-skill install` writes the skill GET /api/agent-skill renders to
- * `<dir>/SKILL.md` (default `.claude/skills/juno` under the current
- * directory) and prints a Claude Code permission block on stdout: every read
- * command, plus every change command with --allow-change, plus the working
- * copy's npm scripts of the same tiers with --working-copy. No act command is
- * ever in it — the server leaves them out, and the CLI adds nothing.
- *
- * `--agents-md` prints the same text as an AGENTS.md section instead and
- * writes nothing; `--json` prints the route's body.
- */
-export async function agentSkillInstall(args, io) {
-  if (args._.length > 0) {
-    throw new UsageError(
-      `juno agent-skill install takes no argument; usage: ${AGENT_SKILL_INSTALL_USAGE}`
-    );
-  }
-  const { client } = await connect(args, io);
-  const skill = await client.getAgentSkill();
-
-  if (args.json) return printJSON(skill, io);
-  if (args['agents-md']) {
-    io.write(skill.agents_md);
-    return 0;
-  }
-
-  const dir = resolve(io.cwd, args.dir ?? SKILL_DIR);
-  const path = join(dir, 'SKILL.md');
-  await mkdir(dir, { recursive: true });
-  await writeFile(path, skill.skill_md, 'utf8');
-
-  const tiers = (t) => [
-    ...(t?.read ?? []),
-    ...(args['allow-change'] ? (t?.change ?? []) : []),
-  ];
-  const allow = tiers(skill.permissions);
-  if (args['working-copy'])
-    allow.push(...tiers(skill.working_copy_permissions));
-
-  io.warn(`wrote ${path} (version ${skill.version})`);
-  io.warn(
-    args['working-copy']
-      ? "Add these rules to this working copy's .claude/settings.json — not to user-wide settings, " +
-          "where they would also allow any other project's npm scripts:"
-      : 'Add these rules to .claude/settings.json (or ~/.claude/settings.json) to run them without a prompt:'
-  );
-  return printJSON({ permissions: { allow } }, io);
-}
-
-/** 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;
-}

package/src/installed-skill.js

@@ -1,55 +0,0 @@
-import { readFile } from 'node:fs/promises';
-import { homedir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
-
-/** Where `juno agent-skill install` writes the skill, relative to a root. */
-export const SKILL_DIR = join('.claude', 'skills', 'juno');
-
-const VERSION_LINE = /^\s*(?:<!--\s*)?juno-skill-version:\s*"?([^"\s]+)"?/m;
-
-/**
- * installedSkill finds the Juno skill a harness would load: SKILL.md under
- * `.claude/skills/juno` in the current directory or the nearest parent that
- * has one, then in the home directory. It answers the first file found and the
- * version it records (null when it records none), or null when there is no
- * file. A file that cannot be read counts as absent: the check it serves is a
- * courtesy, never a failure.
- */
-export async function installedSkill(cwd, env = process.env) {
-  const candidates = [];
-  let dir = resolve(cwd);
-  for (;;) {
-    candidates.push(join(dir, SKILL_DIR, 'SKILL.md'));
-    const parent = dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-  candidates.push(join(env.HOME || homedir(), SKILL_DIR, 'SKILL.md'));
-
-  for (const path of candidates) {
-    let text;
-    try {
-      text = await readFile(path, 'utf8');
-    } catch {
-      continue;
-    }
-    return { path, version: VERSION_LINE.exec(text)?.[1] ?? null };
-  }
-  return null;
-}
-
-/**
- * warnIfStale says on stderr when the installed skill records a version other
- * than the one the instance serves (`agent_skill_version` on GET /api/skills).
- * Silent when either side has none.
- */
-export async function warnIfStale(index, target, io) {
-  const served = index?.agent_skill_version;
-  if (!served) return;
-  const installed = await installedSkill(io.cwd, io.env);
-  if (!installed?.version || installed.version === served) return;
-  io.warn(
-    `the installed Juno skill (${installed.path}) is version ${installed.version}; ` +
-      `${target} serves ${served} — run \`juno agent-skill install\` to update it`
-  );
-}