@junoflow/cli 0.1.0

package/README.md

@@ -0,0 +1,83 @@
+# @junoflow/cli
+
+Develop [Juno](https://github.com/boivie/juno) integrations locally: scaffold a
+project, generate types from your manifest, check it, and deploy it.
+
+```bash
+npm install --save-dev @junoflow/cli
+npx juno init my-integration
+```
+
+An integration is a git repository holding `manifest.json` and TypeScript. Juno
+fetches it at a tag, compiles it, and runs it in a sandbox. There is no
+packaging format and nothing is published to npm.
+
+## Commands
+
+| Command                 | What it does                                                                   |
+| ----------------------- | ------------------------------------------------------------------------------ |
+| `juno init <name>`      | scaffold a project. **No server needed.**                                      |
+| `juno types`            | POST `manifest.json`, write `types/`                                           |
+| `juno check`            | local `tsc --noEmit` + `eslint`, then validate against a Juno (writes nothing) |
+| `juno deploy [--watch]` | upload, verify, activate — and write back the returned types                   |
+| `juno pull`             | write back the manifest and sources the instance holds                         |
+
+### Options
+
+| Flag            | Meaning                                                              |
+| --------------- | -------------------------------------------------------------------- |
+| `--url <url>`   | the instance to talk to                                              |
+| `--name <name>` | address an install under a different name than the manifest declares |
+| `--watch`       | redeploy on every save (`deploy`)                                    |
+| `--force`       | overwrite a dirty working tree (`pull`)                              |
+| `--here`        | scaffold into the current directory (`init`)                         |
+| `--skip-local`  | skip the local tsc/eslint pass (`check`)                             |
+
+## Choosing an instance
+
+In order: `--url`, then `$JUNO_URL`, then `"juno": { "target": … }` in
+`package.json`. A project downloaded from a Juno already has the third, so a
+fresh clone deploys with no setup.
+
+Juno has **no authentication on any endpoint**. An instance is a trusted-LAN
+appliance; do not expose one to the internet.
+
+## The loop
+
+```bash
+npm run watch          # juno deploy --watch
+```
+
+Add an action to `manifest.json`. The types regenerate, and your editor
+immediately red-squiggles `src/integration.ts` because `IntegrationActions` now
+requires a method you have not written — with the parameter and return types
+your JSON Schema implies. The manifest drives the types drive the compiler.
+
+## Why the types are committed
+
+`types/` is generated and checked in. CI needs no Juno, a fresh clone compiles
+offline, and the diff in a pull request shows that adding an action changed the
+interface. Most importantly, a drive-by contributor fixing a bug in someone
+else's integration never needs an instance — only the person changing the
+manifest does.
+
+## What runs where
+
+|                                                                 | offline | needs an instance |
+| --------------------------------------------------------------- | ------- | ----------------- |
+| `tsc --noEmit`, `eslint`, `vitest`                              | ✅      |                   |
+| structural manifest check via `"$schema"` in your editor        | ✅      |                   |
+| reserved names, cross-surface collisions, JSON Schema compiling |         | `juno check`      |
+| `juno types`, `juno deploy`                                     |         | ✅                |
+
+Everything semantic lives in the Go server. This package knows some HTTP
+endpoints and a config preset — that is deliberate, so there is one answer to
+"is this manifest valid" rather than two that can disagree.
+
+## `init` vs. downloading a project
+
+`juno init` and the instance's **Develop locally → Download project** button
+produce the same layout. They differ in what they can know: `init` needs no
+server, while the download can pre-generate `types/` and carries the sources of
+an integration that already exists there. Use `juno pull` afterwards — a second
+download would clobber your working tree.

package/bin/juno.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { run } from '../src/index.js';
+
+process.exitCode = await run(process.argv.slice(2));

package/eslint.config.js

@@ -0,0 +1,38 @@
+import tsParser from '@typescript-eslint/parser';
+import juno from '@junoflow/eslint-plugin';
+
+/**
+ * The lint preset for an integration project.
+ *
+ * It enables exactly the rules Juno enforces server-side for an integration —
+ * `no-juno-sdk-import` and nothing else. The flow-only rules
+ * (`no-dynamic-step-id`, `no-sleep-in-step`) are about `step.run`, which
+ * integrations do not have; enabling them here would report on code that is
+ * fine.
+ *
+ * The one accepted asymmetry: Juno lints the **bundled output** (that is how
+ * `no-juno-sdk-import` catches a surviving `require`), while this lints your
+ * **source**. Both catch it; they catch it differently, and the rule knows both
+ * spellings. It is also why only this half needs a TypeScript parser — by the
+ * time the server lints, esbuild has already turned it into JavaScript.
+ *
+ * `tsconfig.base.json` is the other half of the preset, and a Go test asserts
+ * it matches what Juno type-checks with.
+ */
+export default [
+  {
+    ignores: ['node_modules/**', 'dist/**', 'types/**'],
+  },
+  {
+    files: ['**/*.ts'],
+    languageOptions: {
+      parser: tsParser,
+      ecmaVersion: 2022,
+      sourceType: 'module',
+    },
+    plugins: { juno },
+    rules: {
+      'juno/no-juno-sdk-import': 'error',
+    },
+  },
+];

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@junoflow/cli",
+  "version": "0.1.0",
+  "description": "Command line tools for developing Juno integrations: scaffold, generate types, check and deploy.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/boivie/juno.git",
+    "directory": "tools/npm/cli"
+  },
+  "type": "module",
+  "bin": {
+    "juno": "bin/juno.js"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./package.json": "./package.json",
+    "./tsconfig.base.json": "./tsconfig.base.json",
+    "./eslint.config.js": "./eslint.config.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "tsconfig.base.json",
+    "eslint.config.js",
+    "README.md"
+  ],
+  "keywords": [
+    "juno",
+    "junoflow",
+    "cli",
+    "integration"
+  ],
+  "scripts": {
+    "test": "node --test \"test/**/*.test.js\""
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@junoflow/eslint-plugin": "0.1.0",
+    "@typescript-eslint/parser": "^8.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.0"
+  }
+}

package/src/api.js

@@ -0,0 +1,74 @@
+import { DiagnosticsError, UserError } from './errors.js';
+
+/**
+ * Client for the four endpoints this CLI knows about. It knows nothing
+ * semantic: validation, reserved names, schema compilation and typegen all
+ * live in the Go server, so there is one answer to "is this manifest valid"
+ * rather than two that can disagree.
+ */
+export class JunoClient {
+  constructor(target, { fetch: fetchImpl = globalThis.fetch } = {}) {
+    this.target = target;
+    this.fetch = fetchImpl;
+  }
+
+  /** POST /api/typegen/integration — both .d.ts halves, one call. */
+  async typegen(manifest) {
+    return this.#json('POST', '/api/typegen/integration', { manifest });
+  }
+
+  /** POST /api/integrations/ingest — deploy, or validate only with dryRun. */
+  async ingest(project, { dryRun = false, name } = {}) {
+    const query = dryRun ? '?dry_run=true' : '';
+    return this.#json('POST', `/api/integrations/ingest${query}`, {
+      manifest: project.manifest,
+      files: project.files,
+      package_json: project.packageJSON ?? undefined,
+      lockfile: project.lockfile ?? undefined,
+      name: name ?? undefined,
+    });
+  }
+
+  /** GET /api/integrations/{name} — the manifest and sources Juno holds. */
+  async getIntegration(name) {
+    return this.#json('GET', `/api/integrations/${encodeURIComponent(name)}`);
+  }
+
+  async #json(method, path, body) {
+    const url = `${this.target}${path}`;
+    let res;
+    try {
+      res = await this.fetch(url, {
+        method,
+        headers: body ? { 'content-type': 'application/json' } : {},
+        body: body ? JSON.stringify(body) : undefined,
+      });
+    } catch (err) {
+      throw new UserError(
+        `cannot reach Juno at ${this.target}: ${err.message}`
+      );
+    }
+
+    const text = await res.text();
+    let parsed = null;
+    try {
+      parsed = text ? JSON.parse(text) : null;
+    } catch {
+      // A non-JSON body from a proxy or a wrong URL; reported below as-is.
+    }
+
+    if (res.ok) return parsed;
+
+    // A 422 is the interesting failure: it carries the compiler's own
+    // findings, and reprinting them beats summarising them.
+    if (parsed?.diagnostics?.length) {
+      throw new DiagnosticsError(
+        parsed.detail || 'verification failed',
+        parsed.diagnostics
+      );
+    }
+    const detail =
+      parsed?.detail || parsed?.title || text.trim() || res.statusText;
+    throw new UserError(`${method} ${path} failed (${res.status}): ${detail}`);
+  }
+}

package/src/commands/check.js

@@ -0,0 +1,60 @@
+import { spawn } from 'node:child_process';
+import { join } from 'node:path';
+
+import { JunoClient } from '../api.js';
+import { readProject } from '../project.js';
+import { resolveTarget } from '../target.js';
+
+/**
+ * `juno check` — the offline checks, then the ones only a Juno can answer.
+ *
+ * tsc and eslint run locally against the committed types; reserved names,
+ * cross-surface collisions and JSON Schema compilation need the server, so
+ * they go through ingest?dry_run=1, which stores nothing and is safe to point
+ * at a production instance.
+ */
+export async function check(argv, io) {
+  let failed = false;
+
+  if (!argv['skip-local']) {
+    for (const [label, bin, args] of [
+      ['typecheck', 'tsc', ['--noEmit']],
+      ['lint', 'eslint', ['.']],
+    ]) {
+      const code = await runLocal(bin, args, io);
+      if (code === SKIPPED) {
+        io.warn(`${label}: ${bin} is not installed — run npm install`);
+        continue;
+      }
+      if (code !== 0) failed = true;
+    }
+  }
+
+  const target = await resolveTarget({ url: argv.url, cwd: io.cwd });
+  const client = argv.client ?? new JunoClient(target);
+  const project = await readProject(io.cwd);
+  const result = await client.ingest(project, {
+    dryRun: true,
+    name: argv.name,
+  });
+  for (const warning of result.warnings ?? []) io.warn(`warning: ${warning}`);
+  io.log(`${result.name}: manifest and sources verified against ${target}`);
+
+  return failed ? 1 : 0;
+}
+
+const SKIPPED = -1;
+
+/**
+ * Runs a local devtool from node_modules/.bin. Its output goes straight to the
+ * terminal: tsc and eslint already print file:line:col, and reformatting them
+ * would only lose the column.
+ */
+function runLocal(bin, args, io) {
+  const path = join(io.cwd, 'node_modules', '.bin', bin);
+  return new Promise((resolve) => {
+    const child = spawn(path, args, { cwd: io.cwd, stdio: 'inherit' });
+    child.on('error', () => resolve(SKIPPED));
+    child.on('close', (code) => resolve(code ?? 1));
+  });
+}

package/src/commands/deploy.js

@@ -0,0 +1,85 @@
+import { watch } from 'node:fs';
+import { join } from 'node:path';
+
+import { JunoClient } from '../api.js';
+import { DiagnosticsError } from '../errors.js';
+import { readProject, writeTypes } from '../project.js';
+import { resolveTarget } from '../target.js';
+import { formatDiagnostics } from '../diagnostics.js';
+import { pickTypeFiles } from './types.js';
+
+/** How long to wait for edits to settle before redeploying. */
+const WATCH_DEBOUNCE_MS = 200;
+
+/**
+ * `juno deploy [--watch]` — upload the working copy, verify, activate.
+ *
+ * The response carries the regenerated types, so a deploy keeps the committed
+ * types/ honest without a second round trip that could answer for a different
+ * manifest.
+ */
+export async function deploy(argv, io) {
+  const target = await resolveTarget({ url: argv.url, cwd: io.cwd });
+  const client = argv.client ?? new JunoClient(target);
+
+  if (!argv.watch) {
+    await deployOnce(client, argv, io, target);
+    return 0;
+  }
+  return watchAndDeploy(client, argv, io, target);
+}
+
+async function deployOnce(client, argv, io, target) {
+  const project = await readProject(io.cwd);
+  const result = await client.ingest(project, { name: argv.name });
+  const written = await writeTypes(pickTypeFiles(result.types), io.cwd);
+  for (const warning of result.warnings ?? []) io.warn(`warning: ${warning}`);
+  io.log(
+    `deployed ${result.name} v${result.version} to ${target} (${written.join(', ')})`
+  );
+  return result;
+}
+
+/**
+ * Watch mode is the loop the whole design is for: edit the manifest, the types
+ * regenerate, and the editor red-squiggles the method you have not written yet.
+ * A failed deploy prints and keeps watching — the next save is the retry.
+ */
+async function watchAndDeploy(client, argv, io, target) {
+  io.log(`watching ${io.cwd} — deploying to ${target}`);
+  await runWatchIteration(client, argv, io, target);
+
+  let timer = null;
+  const schedule = () => {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = null;
+      void runWatchIteration(client, argv, io, target);
+    }, WATCH_DEBOUNCE_MS);
+  };
+
+  const watchers = [
+    watch(join(io.cwd, 'src'), { recursive: true }, schedule),
+    watch(join(io.cwd, 'manifest.json'), schedule),
+  ];
+  // Resolves only on SIGINT: watch mode ends when the author ends it.
+  await new Promise((resolve) => {
+    process.once('SIGINT', () => {
+      for (const w of watchers) w.close();
+      resolve();
+    });
+  });
+  return 0;
+}
+
+async function runWatchIteration(client, argv, io, target) {
+  try {
+    await deployOnce(client, argv, io, target);
+  } catch (err) {
+    if (err instanceof DiagnosticsError) {
+      io.error(formatDiagnostics(err.diagnostics));
+    } else {
+      io.error(err.message);
+    }
+  }
+}

package/src/commands/init.js

@@ -0,0 +1,224 @@
+import { mkdir, readFile, writeFile, access } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { UserError } from '../errors.js';
+
+/**
+ * `juno init [name]` — scaffold a project with no server involved.
+ *
+ * This deliberately duplicates what `GET /api/integrations/{name}/package.zip`
+ * generates server-side. It has to: init's whole point is that you can start
+ * without a Juno, and the server's whole point is that it can eject an
+ * integration that already exists there. The two agree on layout and scripts;
+ * only the server's version can pre-generate types/, because only it knows the
+ * manifest's compiled shape.
+ */
+export async function init(argv, io) {
+  const name = argv._[0] ?? argv.name;
+  if (!name) throw new UserError('usage: juno init <name>');
+  if (!/^[a-z][a-z0-9-]*$/.test(name)) {
+    throw new UserError(`"${name}" must be kebab-case: [a-z][a-z0-9-]*`);
+  }
+
+  const dir = resolve(io.cwd, argv.here ? '.' : name);
+  if (!argv.here && (await exists(dir))) {
+    throw new UserError(`${dir} already exists`);
+  }
+
+  const version = await toolingRange();
+  const files = scaffold(
+    name,
+    version,
+    argv.url ?? process.env.JUNO_URL ?? null
+  );
+  for (const [rel, content] of Object.entries(files)) {
+    const path = join(dir, rel);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, content, 'utf8');
+  }
+
+  io.log(`created ${dir}`);
+  io.log('');
+  io.log(argv.here ? 'npm install' : `cd ${name} && npm install`);
+  io.log('npm run types      # generate types/ from manifest.json');
+  io.log('npm test');
+  io.log('npm run deploy');
+  return 0;
+}
+
+/** @junoflow/* are version-locked, so the CLI's own version is the range. */
+async function toolingRange() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const raw = await readFile(join(here, '..', '..', 'package.json'), 'utf8');
+  return `^${JSON.parse(raw).version}`;
+}
+
+function scaffold(name, toolingRange, target) {
+  const pkg = {
+    name,
+    version: '0.1.0',
+    description: '',
+    private: true,
+    type: 'module',
+    scripts: {
+      typecheck: 'tsc --noEmit',
+      lint: 'eslint .',
+      test: 'npm run typecheck && npm run lint && vitest run',
+      types: 'juno types',
+      check: 'juno check',
+      deploy: 'juno deploy',
+      watch: 'juno deploy --watch',
+      pull: 'juno pull',
+    },
+    devDependencies: {
+      '@junoflow/cli': toolingRange,
+      '@junoflow/testkit': toolingRange,
+      eslint: '^9.34.0',
+      typescript: '^5.9.0',
+      vitest: '^3.2.0',
+    },
+    ...(target ? { juno: { target } } : {}),
+  };
+
+  const manifest = {
+    ...(target
+      ? {
+          $schema: `${target.replace(/\/+$/, '')}/api/schemas/integration-manifest.json`,
+        }
+      : {}),
+    name,
+    description: `The ${name} integration.`,
+    config: {
+      apiToken: {
+        type: 'string',
+        credential: true,
+        required: true,
+        title: 'API token',
+        description: 'Filled in by whoever installs this.',
+      },
+    },
+    actions: {
+      ping: {
+        description: 'Replace me with something the service actually does.',
+        params: {
+          type: 'object',
+          properties: { message: { type: 'string' } },
+          required: ['message'],
+          additionalProperties: false,
+        },
+        response: {
+          type: 'object',
+          properties: { ok: { type: 'boolean' } },
+        },
+      },
+    },
+  };
+
+  return {
+    'manifest.json': `${JSON.stringify(manifest, null, 2)}\n`,
+    'package.json': `${JSON.stringify(pkg, null, 2)}\n`,
+    'src/integration.ts': SRC,
+    'test/integration.test.ts': TEST(name),
+    'tsconfig.json': TSCONFIG,
+    'eslint.config.js': ESLINT,
+    '.gitignore': GITIGNORE,
+    '.github/workflows/ci.yml': CI,
+    'README.md': README(name),
+  };
+}
+
+// No imports: every type is an ambient global from types/, and verify rejects
+// an import of juno:sdk.
+const SRC = `export default {
+  actions: {
+    ping: async (params, ctx) => {
+      ctx.log(\`ping: \${params.message}\`);
+      // ctx.config and ctx.credentials are typed from manifest.json's config.
+      return { ok: true };
+    },
+  },
+} satisfies Integration;
+`;
+
+const TEST = (name) => `import { describe, expect, it } from 'vitest';
+import { harness } from '@junoflow/testkit';
+
+import manifest from '../manifest.json';
+import integration from '../src/integration';
+
+const h = harness({ manifest, integration });
+
+describe('${name}', () => {
+  it('conforms to its manifest', () => {
+    expect(h.conformance()).toEqual([]);
+  });
+
+  it('ping returns ok', async () => {
+    h.credentials({ apiToken: 'test-token' });
+    expect(await h.action('ping', { message: 'hello' })).toEqual({ ok: true });
+  });
+});
+`;
+
+const TSCONFIG = `{
+  "extends": "@junoflow/cli/tsconfig.base.json",
+  "include": ["src/**/*.ts", "types/**/*.d.ts", "test/**/*.ts"]
+}
+`;
+
+const ESLINT = `import juno from '@junoflow/cli/eslint.config.js';
+
+export default juno;
+`;
+
+const GITIGNORE = `node_modules/
+dist/
+*.log
+.DS_Store
+`;
+
+const CI = `name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm install
+      - run: npm test
+`;
+
+const README = (name) => `# ${name}
+
+A [Juno](https://github.com/boivie/juno) integration.
+
+\`\`\`bash
+npm install
+npm run types     # generate types/ from manifest.json
+npm test
+npm run deploy
+\`\`\`
+
+\`types/\` is generated and **committed**, so a fresh clone compiles offline and a
+contributor fixing a bug needs no Juno instance. Regenerate it after every
+\`manifest.json\` edit.
+
+Publish by tagging: Juno installs this repository at \`refs/tags/<tag>\`.
+`;
+
+async function exists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/commands/pull.js

@@ -0,0 +1,89 @@
+import { execFile } from 'node:child_process';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { promisify } from 'node:util';
+
+import { JunoClient } from '../api.js';
+import { UserError } from '../errors.js';
+import { readManifest } from '../project.js';
+import { resolveTarget } from '../target.js';
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * `juno pull` — write back the manifest and sources Juno holds.
+ *
+ * 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.
+ */
+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) {
+    throw new UserError(
+      'manifest.json declares no name — pass --name <integration>'
+    );
+  }
+
+  if (!argv.force) {
+    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'
+      );
+    } 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 client = argv.client ?? new JunoClient(target);
+  const detail = await client.getIntegration(name);
+  if (!detail?.manifest) {
+    throw new UserError(
+      `${name} has no active version on ${target} — nothing to pull`
+    );
+  }
+
+  const written = ['manifest.json'];
+  await writeFile(
+    join(io.cwd, 'manifest.json'),
+    `${JSON.stringify(detail.manifest, null, 2)}\n`,
+    'utf8'
+  );
+  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);
+  }
+  io.log(
+    `pulled ${name} v${detail.version} from ${target} (${written.sort().join(', ')})`
+  );
+  io.log('run `juno types` to regenerate types/ against the pulled manifest');
+  return 0;
+}
+
+/**
+ * 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) {
+  try {
+    const { stdout } = await execFileAsync('git', ['status', '--porcelain'], {
+      cwd,
+    });
+    return stdout
+      .split('\n')
+      .map((line) => line.trim())
+      .filter(Boolean);
+  } catch {
+    return null;
+  }
+}

package/src/commands/types.js

@@ -0,0 +1,33 @@
+import { JunoClient } from '../api.js';
+import { readManifest, writeTypes } from '../project.js';
+import { resolveTarget } from '../target.js';
+
+/**
+ * `juno 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 });
+  const manifest = await readManifest(io.cwd);
+  const client = argv.client ?? new JunoClient(target);
+
+  const generated = await client.typegen(manifest);
+  const written = await writeTypes(pickTypeFiles(generated), io.cwd);
+  io.log(`wrote ${written.join(', ')}`);
+  return 0;
+}
+
+/**
+ * The response carries huma's $schema alongside the two files. Filtering by
+ * extension rather than deleting a known key keeps a future third file working
+ * without a CLI release.
+ */
+export function pickTypeFiles(body) {
+  return Object.fromEntries(
+    Object.entries(body ?? {}).filter(([name]) => name.endsWith('.d.ts'))
+  );
+}

package/src/diagnostics.js

@@ -0,0 +1,16 @@
+/**
+ * Render one diagnostic as `file:line:col  message`, the format editors and
+ * CI log parsers already know how to make clickable. A diagnostic with no
+ * position still leads with its file, so the shape never varies.
+ */
+export function formatDiagnostic(d) {
+  const where = [d.file || 'manifest.json', d.line, d.col]
+    .filter(Boolean)
+    .join(':');
+  const code = d.code ? ` [${d.code}]` : '';
+  return `${where}  ${d.message}${code}`;
+}
+
+export function formatDiagnostics(diagnostics) {
+  return diagnostics.map(formatDiagnostic).join('\n');
+}

package/src/errors.js

@@ -0,0 +1,26 @@
+/**
+ * UserError is something the person at the keyboard can fix: a missing target,
+ * an unreadable manifest, a dirty working tree. The top-level handler prints
+ * its message alone and exits 1 — no stack trace, because a stack trace tells
+ * them about our code when the problem is their input.
+ */
+export class UserError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'UserError';
+  }
+}
+
+/**
+ * DiagnosticsError carries a server 422's structured findings. It is separate
+ * from UserError because it renders as a list of file:line:col lines rather
+ * than a sentence — that is what makes an editor's error parser click through
+ * to the offending line.
+ */
+export class DiagnosticsError extends Error {
+  constructor(message, diagnostics) {
+    super(message);
+    this.name = 'DiagnosticsError';
+    this.diagnostics = diagnostics ?? [];
+  }
+}

package/src/index.js

@@ -0,0 +1,114 @@
+import { parseArgs } from 'node:util';
+
+import { check } from './commands/check.js';
+import { deploy } from './commands/deploy.js';
+import { init } from './commands/init.js';
+import { pull } from './commands/pull.js';
+import { types } from './commands/types.js';
+import { DiagnosticsError, UserError } from './errors.js';
+import { formatDiagnostics } from './diagnostics.js';
+
+const COMMANDS = { init, types, check, deploy, pull };
+
+const USAGE = `juno — develop Juno integrations
+
+Usage: juno <command> [options]
+
+Commands:
+  init <name>      scaffold a new integration project (no server needed)
+  types            generate types/ from manifest.json
+  check            typecheck and lint locally, then validate against a Juno
+  deploy [--watch] upload, verify, and activate a new version
+  pull             write back the manifest and sources Juno holds
+
+Options:
+  --url <url>      the Juno instance; else $JUNO_URL, else package.json juno.target
+  --name <name>    address an install under a different name than the manifest
+  --watch          deploy on every save (deploy only)
+  --force          overwrite a dirty working tree (pull only)
+  --here           scaffold into the current directory (init only)
+  --skip-local     skip the local tsc/eslint pass (check only)
+  -h, --help       this
+`;
+
+/**
+ * run is the whole CLI, injectable so the tests drive it without spawning a
+ * process: io carries cwd and the three output streams, and a command may be
+ * handed a client instead of building one from a URL.
+ */
+export async function run(argv, io = defaultIO()) {
+  const [command, ...rest] = argv;
+
+  if (
+    !command ||
+    command === '--help' ||
+    command === '-h' ||
+    command === 'help'
+  ) {
+    io.log(USAGE);
+    return command ? 0 : 1;
+  }
+  const handler = COMMANDS[command];
+  if (!handler) {
+    io.error(`unknown command: ${command}\n`);
+    io.error(USAGE);
+    return 1;
+  }
+
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: rest,
+      allowPositionals: true,
+      options: {
+        url: { type: 'string' },
+        name: { type: 'string' },
+        watch: { type: 'boolean', default: false },
+        force: { type: 'boolean', default: false },
+        here: { type: 'boolean', default: false },
+        'skip-local': { type: 'boolean', default: false },
+        help: { type: 'boolean', short: 'h', default: false },
+      },
+    });
+  } catch (err) {
+    io.error(err.message);
+    return 1;
+  }
+  if (parsed.values.help) {
+    io.log(USAGE);
+    return 0;
+  }
+
+  const args = { ...parsed.values, _: parsed.positionals, client: io.client };
+  try {
+    return (await handler(args, io)) ?? 0;
+  } catch (err) {
+    // Diagnostics print as file:line:col so an editor can click through; a
+    // UserError is a sentence about their input, and neither deserves a stack.
+    if (err instanceof DiagnosticsError) {
+      io.error(formatDiagnostics(err.diagnostics));
+      io.error(`\n${err.diagnostics.length} problem(s): ${err.message}`);
+      return 1;
+    }
+    if (err instanceof UserError) {
+      io.error(err.message);
+      return 1;
+    }
+    throw err;
+  }
+}
+
+export function defaultIO() {
+  return {
+    cwd: process.cwd(),
+    client: null,
+    log: (msg) => process.stdout.write(`${msg}\n`),
+    warn: (msg) => process.stderr.write(`${msg}\n`),
+    error: (msg) => process.stderr.write(`${msg}\n`),
+  };
+}
+
+export { JunoClient } from './api.js';
+export { DiagnosticsError, UserError } from './errors.js';
+export { resolveTarget } from './target.js';
+export { readProject } from './project.js';

package/src/project.js

@@ -0,0 +1,92 @@
+import { readFile, readdir, mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join, posix, relative, sep } from 'node:path';
+
+import { UserError } from './errors.js';
+
+/** Only these reach the server. Everything else is project furniture. */
+const SOURCE_EXTENSIONS = ['.ts', '.json'];
+const SOURCE_DIR = 'src';
+
+/**
+ * Read the four things Juno looks at: manifest.json, the sources under src/,
+ * package.json's dependencies, and the lockfile. types/ and test/ are the
+ * author's — they are never uploaded, and never compiled server-side.
+ */
+export async function readProject(cwd = process.cwd()) {
+  const manifest = await readManifest(cwd);
+  const files = await readSourceFiles(cwd);
+  if (Object.keys(files).length === 0) {
+    throw new UserError(`no TypeScript sources found under ${SOURCE_DIR}/`);
+  }
+  return {
+    manifest,
+    files,
+    packageJSON: await readOptional(join(cwd, 'package.json')),
+    lockfile: await readOptional(join(cwd, 'package-lock.json')),
+  };
+}
+
+export async function readManifest(cwd = process.cwd()) {
+  const path = join(cwd, 'manifest.json');
+  let raw;
+  try {
+    raw = await readFile(path, 'utf8');
+  } catch {
+    throw new UserError(
+      `no manifest.json in ${cwd} — run this from an integration project root`
+    );
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new UserError(`manifest.json is not valid JSON: ${err.message}`);
+  }
+}
+
+/** Walks src/ and returns repo-relative POSIX paths → content. */
+export async function readSourceFiles(cwd = process.cwd()) {
+  const root = join(cwd, SOURCE_DIR);
+  const files = {};
+  async function walk(dir) {
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return; // no src/ at all; the caller reports it
+    }
+    for (const entry of entries) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(full);
+        continue;
+      }
+      if (!SOURCE_EXTENSIONS.some((ext) => entry.name.endsWith(ext))) continue;
+      // Server-side paths are always POSIX: they become keys in a JSON map and
+      // then filenames in a Linux sandbox.
+      const rel = relative(cwd, full).split(sep).join(posix.sep);
+      files[rel] = await readFile(full, 'utf8');
+    }
+  }
+  await walk(root);
+  return files;
+}
+
+/** Writes the .d.ts pair the server returned into types/. */
+export async function writeTypes(types, cwd = process.cwd()) {
+  const written = [];
+  for (const [name, content] of Object.entries(types)) {
+    const path = join(cwd, 'types', name);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, content, 'utf8');
+    written.push(posix.join('types', name));
+  }
+  return written.sort();
+}
+
+async function readOptional(path) {
+  try {
+    return await readFile(path, 'utf8');
+  } catch {
+    return null;
+  }
+}

package/src/target.js

@@ -0,0 +1,46 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { UserError } from './errors.js';
+
+/**
+ * Resolve which Juno instance to talk to, in precedence order: an explicit
+ * --url, then $JUNO_URL, then `juno.target` in package.json — which is what an
+ * ejected project arrives with, so a fresh clone deploys with no setup.
+ *
+ * A missing target names all three: "no target configured" leaves the reader
+ * guessing which of the three they were supposed to have used.
+ */
+export async function resolveTarget({ url, cwd = process.cwd() } = {}) {
+  const candidate =
+    url ?? process.env.JUNO_URL ?? (await targetFromPackageJSON(cwd));
+  if (!candidate) {
+    throw new UserError(
+      'no Juno instance to deploy to. Pass --url <url>, set $JUNO_URL, or add\n' +
+        '  "juno": { "target": "http://juno.local:8080" }\n' +
+        'to package.json.'
+    );
+  }
+  return normalizeTarget(candidate);
+}
+
+async function targetFromPackageJSON(cwd) {
+  try {
+    const raw = await readFile(join(cwd, 'package.json'), 'utf8');
+    return JSON.parse(raw).juno?.target ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** Accepts a bare host the way a browser address bar does. */
+export function normalizeTarget(target) {
+  let t = target.trim().replace(/\/+$/, '');
+  if (!/^https?:\/\//.test(t)) t = `http://${t}`;
+  try {
+    new URL(t);
+  } catch {
+    throw new UserError(`not a usable Juno URL: ${target}`);
+  }
+  return t;
+}

package/tsconfig.base.json

@@ -0,0 +1,13 @@
+{
+  "//": "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": {
+    "esModuleInterop": true,
+    "module": "CommonJS",
+    "moduleResolution": "node",
+    "noEmit": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "target": "ES2022"
+  }
+}