@junoflow/cli 0.11.0 → 0.12.0

package/README.md

@@ -185,6 +185,14 @@ The group's working-copy commands (`integration init`, `gen-types`,
 | `juno credential list`     | `list_credentials` | —             | read   |
 | `juno credential set <id>` | none               | credential id | act    |
 
+**`person`**
+
+| Command             | Tool           | Positional | Effect |
+| ------------------- | -------------- | ---------- | ------ |
+| `juno person list`  | `list_people`  | —          | read   |
+| `juno person get`   | `get_person`   | `id`       | read   |
+| `juno person write` | `write_person` | `id`       | change |
+
 **`ha`** (Home Assistant)
 
 | Command                      | Tool                 | Positional  | Effect |
@@ -518,6 +526,29 @@ keeps them in `package.json` alone, so there `pull` leaves `dependencies` as it
 is. It refuses to overwrite uncommitted changes in a git working tree unless you
 pass `--force`.
 
+### The source, and the warning
+
+Every kind's `check` and `deploy` send where the working copy sits in git: the
+`origin` remote (the first remote without one; any user, password, query or
+fragment stripped), the `HEAD` sha, and `dirty` when `git status` reports a
+change or an untracked file under the working copy's directory. Outside git, or
+before the first commit, they send nothing and deploy as usual. Juno records it
+on the version, which is from then on **remote**: its source of truth is this
+working copy, not Juno.
+
+When a deploy moves the artifact's source, or replaces a version written in Juno
+since your last pull, the instance answers one sentence and the CLI prints it on
+stderr:
+
+```text
+warning: flow "porch-light" was local; v8 is remote from now on — change it in the working copy and deploy.
+```
+
+It is never a failure: the deploy has happened, and the exit code is what it
+would have been. `check` prints the warning the deploy would. With `--json` the
+sentence is the body's `source_warning`. See
+[Where the Source Lives](https://boivie.github.io/juno/assistant/source/).
+
 ## Flows as files
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@junoflow/cli",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Develop Juno flows, integrations and apps, and operate a Juno instance from the command line",
   "license": "MIT",
   "repository": {
@@ -40,7 +40,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@junoflow/eslint-plugin": "0.11.0",
+    "@junoflow/eslint-plugin": "0.12.0",
     "@typescript-eslint/parser": "^8.0.0"
   },
   "devDependencies": {

package/src/api.js

@@ -87,9 +87,10 @@ export class JunoClient {
    *
    * It does not go through #workingCopyJSON, whose 422-without-diagnostics
    * wording differs from what this route has always printed; only the 409 is
-   * shared.
+   * shared. `origin` (gitOrigin) is sent when given, dry runs included: they
+   * stamp nothing, but their source_warning says what a deploy would.
    */
-  async ingest(project, { dryRun = false, id, baseVersion } = {}) {
+  async ingest(project, { dryRun = false, id, baseVersion, origin } = {}) {
     const path = `/api/integrations/ingest${dryRun ? '?dry_run=true' : ''}`;
     const res = await this.#request('POST', path, {
       manifest: project.manifest,
@@ -98,6 +99,7 @@ export class JunoClient {
       lockfile: project.lockfile ?? undefined,
       id: id ?? undefined,
       base_version: baseVersion ?? undefined,
+      origin: origin ?? undefined,
     });
     if (res.status === 409) throw new ConflictError(problemDetail(res));
     return this.#answer('POST', path, res);
@@ -187,16 +189,20 @@ export class JunoClient {
    * POST /api/flows/ingest — verify a flow working copy and, unless dryRun,
    * commit and activate it. `files` is the working copy's src/ tree, path →
    * content. `baseVersion` undefined sends none (a new flow,
-   * or --force). A 409 is a ConflictError; a 422 with diagnostics is a
-   * DiagnosticsError.
+   * or --force). `origin` (gitOrigin) is sent when given. A 409 is a
+   * ConflictError; a 422 with diagnostics is a DiagnosticsError.
    */
-  async ingestFlow({ flowId, manifest, files, baseVersion }, { dryRun } = {}) {
+  async ingestFlow(
+    { flowId, manifest, files, baseVersion },
+    { dryRun, origin } = {}
+  ) {
     const query = dryRun ? '?dry_run=true' : '';
     return this.#workingCopyJSON(`/api/flows/ingest${query}`, {
       flow_id: flowId,
       manifest,
       files,
       base_version: baseVersion ?? undefined,
+      origin: origin ?? undefined,
     });
   }
 
@@ -227,11 +233,12 @@ export class JunoClient {
    * `baseVersion` undefined sends none (a copy that records no base, or
    * --force). When activating, a 409 is a ConflictError: the app's active
    * version is not the copy's base. A draft is never refused; the answer's
-   * `stale_base` carries the sentence instead.
+   * `stale_base` carries the sentence instead. `origin` (gitOrigin) is sent
+   * when given.
    */
   async ingestApp(
     { manifest, files, lockfile },
-    { activate = true, baseVersion } = {}
+    { activate = true, baseVersion, origin } = {}
   ) {
     return this.#workingCopyJSON('/api/apps/ingest', {
       manifest,
@@ -239,6 +246,7 @@ export class JunoClient {
       lockfile: lockfile ?? undefined,
       activate,
       base_version: baseVersion ?? undefined,
+      origin: origin ?? undefined,
     });
   }
 

package/src/commands/app-check.js

@@ -1,10 +1,15 @@
 import { connect } from '../api.js';
 import { readAppProject } from '../app-project.js';
-import { printDiagnosticsJSON, printJSON } from '../diagnostics.js';
+import {
+  printDiagnosticsJSON,
+  printJSON,
+  printSourceWarning,
+} 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';
+import { gitOrigin } from '../working-copy.js';
 
 export const APP_CHECK_USAGE = 'juno app check [--skip-local] [--json]';
 
@@ -35,6 +40,7 @@ export async function appCheck(argv, io) {
     result = await client.ingestApp(project, {
       activate: false,
       baseVersion: project.baseVersion,
+      origin: await gitOrigin(io.cwd, io.env),
     });
   } catch (err) {
     if (argv.json && err instanceof DiagnosticsError) {
@@ -47,6 +53,7 @@ export async function appCheck(argv, io) {
     printJSON(result, io);
   } else {
     for (const w of result.warnings ?? []) io.warn(`warning: ${w}`);
+    printSourceWarning(result, io);
     io.log(
       `${result.id}: verified and stored as draft v${result.version} on ${target}`
     );

package/src/commands/app-deploy.js

@@ -8,10 +8,15 @@ import {
   SRC_DIR,
   updateAppPackage,
 } from '../app-project.js';
-import { printDiagnosticsJSON, printJSON } from '../diagnostics.js';
+import {
+  printDiagnosticsJSON,
+  printJSON,
+  printSourceWarning,
+} from '../diagnostics.js';
 import { DiagnosticsError } from '../errors.js';
 import { deployOnChange } from '../watch.js';
 import {
+  gitOrigin,
   MANIFEST,
   manifestText,
   typeFiles,
@@ -79,6 +84,7 @@ export async function appDeploy(argv, io) {
 async function deployProject(client, project, argv, io, target) {
   const result = await client.ingestApp(project, {
     baseVersion: argv.force ? undefined : project.baseVersion,
+    origin: await gitOrigin(io.cwd, io.env),
   });
 
   const manifestRaw = manifestText(result.manifest);
@@ -97,6 +103,7 @@ async function deployProject(client, project, argv, io, target) {
     printJSON(result, io);
   } else {
     for (const w of result.warnings ?? []) io.warn(`warning: ${w}`);
+    printSourceWarning(result, io);
     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}`);

package/src/commands/check.js

@@ -2,11 +2,16 @@ import { spawn } from 'node:child_process';
 import { join } from 'node:path';
 
 import { connect } from '../api.js';
-import { printDiagnosticsJSON, printJSON } from '../diagnostics.js';
+import {
+  printDiagnosticsJSON,
+  printJSON,
+  printSourceWarning,
+} from '../diagnostics.js';
 import { DiagnosticsError, UserError } from '../errors.js';
 import { readProject } from '../project.js';
 import { baseFor } from './deploy.js';
 import { verifyTypes } from './verify-types.js';
+import { gitOrigin } from '../working-copy.js';
 
 export const CHECK_USAGE =
   'juno integration check [--skip-local] [--id <id>] [--json]';
@@ -48,6 +53,7 @@ export async function check(argv, io) {
       dryRun: true,
       id: argv.id,
       baseVersion: baseFor(project, argv, io),
+      origin: await gitOrigin(io.cwd, io.env),
     });
   } catch (err) {
     if (argv.json && err instanceof DiagnosticsError) {
@@ -60,6 +66,7 @@ export async function check(argv, io) {
     printJSON(result, io);
   } else {
     for (const w of result.warnings ?? []) io.warn(`warning: ${w}`);
+    printSourceWarning(result, io);
     io.log(`${result.id}: manifest and sources verified against ${target}`);
   }
 

package/src/commands/deploy.js

@@ -1,7 +1,11 @@
 import { join } from 'node:path';
 
 import { connect } from '../api.js';
-import { printDiagnosticsJSON, printJSON } from '../diagnostics.js';
+import {
+  printDiagnosticsJSON,
+  printJSON,
+  printSourceWarning,
+} from '../diagnostics.js';
 import { DiagnosticsError } from '../errors.js';
 import {
   readManifestRaw,
@@ -12,6 +16,7 @@ import {
 import { stampTypeFiles } from '../stamp.js';
 import { pickTypeFiles } from './gen-types.js';
 import { deployOnChange } from '../watch.js';
+import { gitOrigin } from '../working-copy.js';
 
 export const DEPLOY_USAGE =
   'juno integration deploy [--watch] [--force] [--id <id>] [--json]';
@@ -57,6 +62,7 @@ async function deployOnce(client, argv, io, target) {
   const result = await client.ingest(project, {
     id: argv.id,
     baseVersion: argv.force ? undefined : baseFor(project, argv, io),
+    origin: await gitOrigin(io.cwd, io.env),
   });
   // Stamped against the manifest this deploy was built from, so the watch loop
   // leaves a tree that `juno integration verify-types` accepts.
@@ -82,6 +88,7 @@ async function deployOnce(client, argv, io, target) {
     return result;
   }
   for (const warning of result.warnings ?? []) io.warn(`warning: ${warning}`);
+  printSourceWarning(result, io);
   io.log(
     `deployed ${result.id} v${result.version} to ${target} (${written.sort().join(', ')})`
   );

package/src/commands/flow-check.js

@@ -2,7 +2,12 @@ import { connect } from '../api.js';
 import { DiagnosticsError } from '../errors.js';
 import { readFlowProject } from '../flow-project.js';
 import { runLocalChecks } from './check.js';
-import { printDiagnosticsJSON, printJSON } from '../diagnostics.js';
+import {
+  printDiagnosticsJSON,
+  printJSON,
+  printSourceWarning,
+} from '../diagnostics.js';
+import { gitOrigin } from '../working-copy.js';
 import { printWarnings } from './flow-deploy.js';
 
 export const FLOW_CHECK_USAGE = 'juno flow check [--skip-local] [--json]';
@@ -28,7 +33,7 @@ export async function flowCheck(argv, io) {
         files: project.files,
         baseVersion: project.baseVersion,
       },
-      { dryRun: true }
+      { dryRun: true, origin: await gitOrigin(io.cwd, io.env) }
     );
   } catch (err) {
     if (argv.json && err instanceof DiagnosticsError) {
@@ -41,6 +46,7 @@ export async function flowCheck(argv, io) {
     printJSON(result, io);
   } else {
     printWarnings(result.warnings, io);
+    printSourceWarning(result, io);
     io.log(`${result.flow_id}: manifest and src/ verified against ${target}`);
   }
   return failed ? 1 : 0;

package/src/commands/flow-deploy.js

@@ -6,6 +6,7 @@ import {
   formatDiagnostic,
   printDiagnosticsJSON,
   printJSON,
+  printSourceWarning,
 } from '../diagnostics.js';
 import {
   MANIFEST,
@@ -17,6 +18,7 @@ import {
   writeFlowFiles,
 } from '../flow-project.js';
 import { deployOnChange } from '../watch.js';
+import { gitOrigin } from '../working-copy.js';
 
 export const FLOW_DEPLOY_USAGE =
   'juno flow deploy [--watch] [--force] [--json]';
@@ -73,12 +75,15 @@ async function deployOnce(client, argv, io, target) {
 }
 
 async function deployProject(client, project, argv, io, target) {
-  const result = await client.ingestFlow({
-    flowId: project.flowId,
-    manifest: project.manifest,
-    files: project.files,
-    baseVersion: argv.force ? undefined : project.baseVersion,
-  });
+  const result = await client.ingestFlow(
+    {
+      flowId: project.flowId,
+      manifest: project.manifest,
+      files: project.files,
+      baseVersion: argv.force ? undefined : project.baseVersion,
+    },
+    { origin: await gitOrigin(io.cwd, io.env) }
+  );
 
   const manifestRaw = manifestText(result.manifest);
   const written = await writeFlowFiles(io.cwd, {
@@ -96,6 +101,7 @@ async function deployProject(client, project, argv, io, target) {
     printJSON(result, io);
   } else {
     printWarnings(result.warnings, io);
+    printSourceWarning(result, io);
     const files = written.length ? ` (${written.sort().join(', ')})` : '';
     io.log(
       `deployed ${result.flow_id} v${result.version} to ${target}${files}`

package/src/diagnostics.js

@@ -28,3 +28,13 @@ export function printDiagnosticsJSON(err, io) {
   printJSON({ detail: err.message, diagnostics: err.diagnostics }, io);
   return 1;
 }
+
+/**
+ * A route's `source_warning` — the server's sentence for a deploy that moves
+ * an artifact between sources (local, installed, remote) or supersedes a
+ * version written in Juno — on stderr as `warning: …`. Never a failure: the
+ * write already happened, or a check says what a deploy would do.
+ */
+export function printSourceWarning(result, io) {
+  if (result?.source_warning) io.warn(`warning: ${result.source_warning}`);
+}

package/src/working-copy.js

@@ -249,6 +249,66 @@ export async function dirtyPaths(cwd) {
   }
 }
 
+/**
+ * gitOrigin is where this working copy sits in git, as the `origin` every
+ * ingest route accepts: `{git: {remote, sha, dirty}}` — the origin remote's
+ * URL (the first remote when there is no `origin`, none when there is no
+ * remote), HEAD's sha, and whether `git status --porcelain` reports anything
+ * under this directory, untracked files included. Scoped to the working copy,
+ * so changes elsewhere in a monorepo do not make it dirty.
+ *
+ * Best effort and never fatal: not a repository, no commit yet, no git on
+ * PATH or any other failure answers undefined, and the deploy goes ahead
+ * without it. The remote loses any credentials here; the server strips them
+ * again rather than trusting this.
+ */
+export async function gitOrigin(cwd, env) {
+  const git = async (...args) =>
+    (await execFileAsync('git', args, { cwd, env })).stdout;
+  try {
+    const sha = (await git('rev-parse', 'HEAD')).trim();
+    const dirty = (await git('status', '--porcelain', '--', '.')).trim() !== '';
+    let remote = '';
+    try {
+      remote = (await git('remote', 'get-url', 'origin')).trim();
+    } catch {
+      const first = (await git('remote')).split('\n')[0].trim();
+      if (first) remote = (await git('remote', 'get-url', first)).trim();
+    }
+    remote = stripCredentials(remote);
+    return {
+      git: {
+        ...(remote ? { remote } : {}),
+        sha,
+        ...(dirty ? { dirty } : {}),
+      },
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * stripCredentials drops what can carry a secret from a URL remote — its
+ * userinfo, query and fragment (`https://user:token@host/o/r` →
+ * `https://host/o/r`). An scp-like remote (`git@host:o/r.git`) names a user
+ * and no secret, and is kept. A URL that does not parse is dropped rather
+ * than guessed at.
+ */
+export function stripCredentials(remote) {
+  if (!remote.includes('://')) return remote;
+  try {
+    const u = new URL(remote);
+    u.username = '';
+    u.password = '';
+    u.search = '';
+    u.hash = '';
+    return u.toString();
+  } catch {
+    return '';
+  }
+}
+
 export async function readText(cwd, name) {
   try {
     return await readFile(join(cwd, name), 'utf8');

package/tsconfig.base.json

@@ -2,6 +2,7 @@
   "//": "The compiler options Juno type-checks with server-side. internal/verify's tsconfig_preset_test.go asserts this file and verify.CompilerOptions() are identical, so `tsc --noEmit` passing here means the deploy will not 422 on a type error. Extend it; do not fork it.",
   "compilerOptions": {
     "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable", "ESNext.Disposable"],
     "module": "CommonJS",
     "moduleResolution": "node",
     "strict": true,

package/verbs.json

@@ -222,6 +222,20 @@
     { "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": "person list", "tool": "list_people" },
+    { "command": "person get", "tool": "get_person", "id_field": "id" },
+    { "command": "person write", "tool": "write_person", "id_field": "id" },
+    {
+      "command": "question list",
+      "tool": "list_questions",
+      "flags": { "closed": { "field": "closed", "type": "string" } }
+    },
+    {
+      "command": "question get",
+      "tool": "get_question",
+      "id_field": "run_id",
+      "flags": { "handle": { "field": "handle_id", "type": "string" } }
+    },
     {
       "command": "ha get-entity",
       "tool": "get_entity",