@ekanos/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vastly
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,326 @@
+# @ekanos/cli
+
+The Ekanos partner toolchain. Scaffold, validate, and test a Fusion integration
+against the published `@ekanos` packages — from any Node project, with no
+bundler and no dependency on `@ekanos/sdk` at runtime.
+
+```bash
+npx @ekanos/cli init --slug my-integration --yes   # works in an empty dir, or merges into an existing package.json
+npx @ekanos/cli validate
+npx @ekanos/cli test
+npx @ekanos/cli dev
+```
+
+## Verbs
+
+| Verb | What it does |
+|---|---|
+| `init` | Scaffold `ekanos.json`, a working `defineIntegration`, a test, a `tsconfig.json`, a vitest config, `.gitignore`, and a `package.json` with real published deps. Runs in an empty directory or on top of an existing project. |
+| `validate` | Load the definition via esbuild and validate it with the **real** `@ekanos/integration-schema` zod schemas; add project checks (the required vitest SDK-inline block). |
+| `dev` | Scaffold `.ekanos/harness/` and run it with **your** Next, so your widgets, tile, activation form and triggers render in real Fusion chrome. |
+| `test` | Delegate to the project's own test script via its package manager. |
+| `login` | Authenticate this machine against a Fusion deployment (Auth0 device flow). |
+| `logout` | Revoke the session at Auth0 and delete the local credentials. |
+| `whoami` | Print the identity the stored session authenticates as. |
+
+## Global flags
+
+| Flag | What it does |
+|---|---|
+| `--json` | Force the JSON envelope on, even at a terminal. |
+| `--no-json` | Force the human-readable form on, even when piped. |
+| `--version` | Print the CLI version and exit 0. Works with or without a verb. |
+| `--help` | Print usage. Also available per-verb (`ekanos validate --help`). |
+
+Short flags are not supported — the parser rejects them rather than guessing.
+
+## Agent-native envelope
+
+Every verb speaks JSON. JSON mode is **inferred** from a non-TTY stdout or
+`CLAUDECODE=1`, and an explicit `--json` / `--no-json` overrides that inference
+in either direction. In JSON mode **stdout carries exactly one JSON object** —
+`{ ok, data, error: { code, message, hint } }` — and every progress line goes to
+stderr. Errors always carry an imperative `hint`.
+
+The CLI never prompts, in any mode. `init` requires `--slug` and fails with a
+usage error naming the flag rather than asking for it.
+
+### Exit codes (frozen public contract)
+
+`0` ok · `1` internal · `2` usage · `3` validation-findings · `4` auth-required ·
+`5` forbidden · `6` not-found · `7` invalid-state · `8` network ·
+`9` precondition-failed · `10` gate-failed.
+
+## `ekanos.json`
+
+```json
+{ "slug": "my-integration", "entry": "src/integration.ts" }
+```
+
+More than one integration in a project? Use the list form instead — `validate`
+then cross-checks them against each other (colliding slugs, widget ids, tool
+names), which it cannot do when it can only see one:
+
+```json
+{ "integrations": [
+    { "slug": "acme-crm",     "entry": "src/crm.ts" },
+    { "slug": "acme-billing", "entry": "src/billing.ts" }
+] }
+```
+
+Declare one form or the other, never both. `validate` also checks that each
+`slug` here agrees with the `slug` in the definition it points at — they
+address the same integration everywhere, so a disagreement is an error rather
+than a warning.
+
+### Every field
+
+| Field | Required | Where | What |
+|---|---|---|---|
+| `slug` | yes, in the single form | top level | kebab-case; must equal the definition's `slug` |
+| `entry` | yes, in the single form | top level | path to the module exporting your `defineIntegration(...)` result |
+| `integrations[]` | yes, in the list form | top level | `{ slug, entry }` per integration, same rules, slugs unique |
+| `sourceGlobs` | no | **top level only** | extra Tailwind `@source` globs; project-relative, no `..` |
+| `$schema` | no | top level | ignored, for editor tooling |
+
+The file is **strict**: an unrecognised key is an error naming the key, not a
+silent no-op. `sourceGlobs` is deliberately not per-integration — Tailwind scans
+one content set for the whole shell, so splitting it per integration would
+imply an isolation that does not exist.
+
+### The generated shell
+
+`ekanos dev` writes exactly this, and rewrites any of it whose bytes drift:
+
+```
+.ekanos/harness/
+  .ekanos-version              { harness, cli, templates } — what generated this
+  app/layout.tsx               stylesheet + metadata + shell re-export
+  app/harness-shell.tsx        'use client' — injects your registry
+  app/page.tsx                 server component — the index
+  app/[slug]/layout.tsx        ─┐
+  app/[slug]/widgets/page.tsx   │
+  app/[slug]/widgets/[widgetId]/page.tsx
+  app/[slug]/tile/page.tsx      ├─ one-line re-exports of @ekanos/harness/routes
+  app/[slug]/activation/page.tsx
+  app/[slug]/triggers/page.tsx ─┘
+  next.config.mjs              transpiles @ekanos/harness, aliases the workspace mock
+  postcss.config.mjs           @tailwindcss/postcss
+  tsconfig.json                no baseUrl, no paths
+  styles/globals.css           @import '@ekanos/harness/styles.css' + your @source globs
+  types/team-accounts.d.ts     types the workspace mock through the export map
+  package.json                 scripts only — no deps, everything resolves upward
+```
+
+`next dev`/`next build` add `next-env.d.ts`, `.next/`, and (Next 16)
+`AGENTS.md`/`CLAUDE.md` alongside them. None of that is ours and none of it is
+tracked — `.ekanos/` is gitignored in full.
+
+`entry` points at the module exporting your `defineIntegration(...)` result
+(default export, or any named export that is an object with a string `slug`).
+
+## `ekanos dev`
+
+```bash
+pnpm add -D @ekanos/harness next react react-dom tailwindcss @tailwindcss/postcss
+npx @ekanos/cli dev                 # scaffold, then run on http://localhost:3100
+npx @ekanos/cli dev --port 4000
+npx @ekanos/cli dev --no-start      # scaffold only
+npx @ekanos/cli dev --host 0.0.0.0  # expose on your network — read below first
+```
+
+### The harness binds loopback
+
+`dev` passes `--hostname 127.0.0.1` to Next, which by default would bind
+`0.0.0.0`. The harness has no authentication and renders your fixtures — and,
+in live mode, real responses from your vendor API — so on a shared network a
+default wildcard bind hands all of that to anyone who can reach the port.
+
+`--host` opts in explicitly (for a phone on the same Wi-Fi, say). It prints a
+warning saying what is now reachable, and the JSON envelope carries
+`server.exposed: true` so a script can refuse to run that way.
+
+### Who owns what
+
+| Path | Owner | You edit it? |
+|---|---|---|
+| `harness.config.ts` (project root) | **you** | **yes — the only one.** Written once, git-tracked, never touched again. |
+| your integration source | **you** | yes |
+| `.ekanos/harness/**` | generated | no — gitignored, rewritten on every run |
+| `@ekanos/harness` | us | no — it is an ordinary dependency |
+
+That split is the point: a harness bugfix ships as an `@ekanos/harness` version
+bump you pick up with `pnpm up`, with zero edits to any file you own. Every
+file in the generated shell is mechanical — re-exports of
+`@ekanos/harness/routes`, an app shell that injects your registry, and
+configs — so none of it ever needs a judgment call from you;
+[The generated shell](#the-generated-shell) above is the exact list.
+`.ekanos/harness/.ekanos-version` records which `@ekanos/harness` generated it,
+and when that disagrees with the installed version the shell is regenerated
+automatically and `dev` says so on stderr.
+
+Re-running is free: files whose bytes already match are not rewritten (so Next's
+watcher stays quiet), and `.ekanos/` is added to `.gitignore` exactly once.
+`--force` rewrites the generated shell; nothing rewrites `harness.config.ts`.
+
+`dev` refuses to write through a symlink, to write outside your project, or to
+overwrite a `.ekanos/harness` it did not generate (one with no `.ekanos-version`
+marker) unless you pass `--force`. Each exits 7 having changed nothing.
+
+### One constraint on your own code
+
+`harness.config.ts` is imported from both a server component and a client
+component, so everything reachable from it must be importable in both graphs.
+Deriving fixture query keys from a `'use client'` module compiles and then
+fails at request time with `Attempted to call … from the server`. Move the key
+builders into a plain module with no `'use client'` directive and have your
+hooks import that — which is also how you keep fixtures and hooks from
+drifting apart.
+
+### Where your source lives
+
+The generated `styles/globals.css` points Tailwind at the usual places
+(`src/`, `app/`, `lib/`, `components/`, `integrations/`, `packages/`). If your
+integration lives somewhere else, add globs to `ekanos.json` — do NOT edit the
+stylesheet, which is regenerated on every run:
+
+```json
+{ "slug": "acme-crm", "entry": "src/integration.ts",
+  "sourceGlobs": ["vendor/acme/**/*.{ts,tsx}"] }
+```
+
+A glob Tailwind is not pointed at costs you a silently unstyled integration
+with no build error, so these are validated strictly: project-relative, no
+`..`, and a restricted character set, because they are written verbatim into
+generated CSS.
+
+### Version compatibility
+
+The shell templates ship with `@ekanos/cli`; the code they import ships with
+`@ekanos/harness`. Both declare a **shell contract** — an integer that changes
+only when the shell a harness requires changes (an export moving, the
+server/client split, the set of files). `dev` compares them before it writes
+anything and names the mismatch — `@ekanos/cli 0.1.0 is too old for
+@ekanos/harness 0.2.0: that harness needs shell contract 2, and this CLI
+generates 1` — rather than letting it surface later as a module-resolution
+error. A version bump that does not change the contract never blocks an
+upgrade.
+
+`.ekanos/harness/.ekanos-version` records the harness version, the CLI version
+and a hash of the templates, so a change to any of them regenerates the shell
+and `dev` says which one moved.
+
+**For maintainers:** propagation is byte-driven — `dev` rewrites a generated
+file whenever its content differs, marker or not. So a change to the SHELL
+ships in an `@ekanos/cli` release, never a harness one: bumping
+`@ekanos/harness` alone cannot deliver a new template, because the templates
+are not in that package. Bump `SHELL_CONTRACT` in
+`src/compatibility.ts` only when the coupling changes, not for every template
+edit.
+
+### For agents
+
+`dev` in JSON mode (`--json`, a pipe, or `CLAUDECODE=1`) **scaffolds and
+returns** rather than blocking on a dev server that never exits — the envelope's
+`data.server` carries `{ started: false, command, url, port }` so the caller can
+start it itself. Pass `--start` to override.
+
+## `ekanos init` on an existing project
+
+`npm init -y` first is fine. `init` **merges** into a `package.json` you
+already have rather than skipping it: missing dependencies, devDependencies and
+scripts are added, and anything you already set is left alone — your pinned
+version and your own `test` script are decisions, not omissions.
+
+Deliberate exceptions:
+
+- `npm init -y`'s stub `test` script (`echo "Error: no test specified" && exit
+  1`) is replaced. It is npm's placeholder, not a choice, and keeping it left
+  `ekanos test` failing on a fresh scaffold.
+- `"type"` is set to `module` even if you declare `"commonjs"`, with a loud
+  note saying it changed. `npm init -y` writes `"commonjs"` explicitly, so that
+  is the mainline rather than an edge case — and the files this scaffolder
+  writes are ESM TypeScript that cannot load under it. Leaving it would mean
+  writing files that do not run. If the project has CommonJS sources of its
+  own, revert that line and put your integration in its own package: the two
+  module systems cannot share one `package.json`.
+
+Every verb after `init` fails fast with `precondition_failed` (exit 9) if
+`"type"` is not `module`, naming the file and the fix — so missing the note
+costs you one clear error rather than a module-resolution failure from inside
+Node or Next.
+
+Anything `init` does not do is reported with a hint saying what to do about it —
+`data.skipped[]` carries `{ file, reason, hint }`, and `data.manifest.notes[]`
+carries the same for manifest fields it could not resolve.
+
+## Authentication
+
+```bash
+ekanos login --host https://your-fusion-host    # or set EKANOS_HOST
+ekanos whoami --host https://your-fusion-host
+ekanos logout --host https://your-fusion-host
+```
+
+`login` uses the **OAuth 2.0 device authorization flow**: it prints a short code
+and a URL to **stderr**, and you approve the request in a browser on any device.
+That is deliberate — a loopback/PKCE login needs a browser on the same machine
+and a bindable localhost port, which is exactly what you do not have over SSH or
+inside a container.
+
+There is nothing to configure on your side. The CLI asks the host for its Auth0
+domain, client id and scope (`GET /api/auth/cli-config`), so one binary works
+against a sandbox and production.
+
+### Where credentials live
+
+`~/.ekanos/credentials.json`, mode **0600**, inside a `~/.ekanos` directory
+forced to **0700**, keyed by host so several deployments can be held at once.
+Set `EKANOS_HOME` to relocate it (containers, CI).
+
+If either is found group- or world-accessible, the CLI tightens the permissions
+and warns on stderr — it does not refuse to run, but it does tell you, and you
+should assume the token was exposed and re-run `ekanos logout && ekanos login`.
+
+The file holds the rotating Auth0 refresh token plus a short-lived Fusion JWT.
+No token is ever printed: not by `whoami`, not in an error, not in a `--json`
+envelope, not at any log level.
+
+### Idempotence
+
+- `login` with a session that still works reports `already-authenticated` and
+  never opens a browser. `--force` starts a fresh login regardless.
+- `logout` twice succeeds; the second run reports `cleared: false`.
+- `logout` revokes at Auth0 first, but a failed revocation never stops the local
+  delete — it is reported as `revoked: false` with a warning on stderr.
+
+### Rotation safety
+
+Auth0 rotates the refresh token the moment the server's exchange succeeds, so
+from that instant the replacement is the only copy in existence — and
+`/api/auth/cli-refresh` can still fail afterwards. It therefore returns the
+rotated token on its error responses too, and the CLI persists it the moment it
+is seen, before surfacing any error. A transient upstream blip costs you a
+retry, not your session.
+
+Two hazards, both handled and worth telling apart:
+
+- **Rotate-then-fail** (single process): the refresh rotates and a later step
+  fails. Handled as above — retry, no re-login.
+- **Concurrent rotation** (two processes sharing one credentials file): both
+  present the same token, Auth0 honours the first, the second gets a clean
+  exit 4. No file lock; re-run `ekanos login`.
+
+### Exit codes to branch on
+
+`4` (auth-required) means "run `ekanos login`" — no session, an expired one that
+could not be renewed, or a revoked one. `8` (network) means the host was
+unreachable, or the refresh rotated but could not complete; it is **not** a
+signal to log in again — retry it.
+
+### What this does and does not grant
+
+`login` establishes **identity**. What that identity is permitted to do is a
+separate concern, handled by Fusion's own authorization; the CLI adds no
+permissions of its own and no path to acquire any.
+

package/dist/auth/credential-store.d.ts

@@ -0,0 +1,96 @@
+export interface StoredSession {
+    /** The Auth0 refresh token. Rotating — replaced on every refresh. */
+    auth0RefreshToken: string;
+    /** The minted Fusion JWT. Short-lived; re-minted from the refresh token. */
+    accessToken: string;
+    /** ISO-8601 expiry of `accessToken`, as reported by the server. */
+    expiresAt: string;
+    userId: string;
+    email: string | null;
+    /** ISO-8601 timestamp of the last write. */
+    updatedAt: string;
+}
+export interface CredentialStoreOptions {
+    /**
+     * Overrides the home directory. `EKANOS_HOME` is honoured by the caller;
+     * tests pass a temp dir. Never read from `process.env` in here so the store
+     * is deterministic under test.
+     */
+    home: string;
+    /** Where permission warnings go. Always stderr in production. */
+    warn?: (message: string) => void;
+}
+export declare class CredentialStore {
+    private readonly dir;
+    private readonly file;
+    private readonly warn;
+    constructor(options: CredentialStoreOptions);
+    /** Absolute path to the credentials file — safe to print. */
+    get filePath(): string;
+    /**
+     * Read the session for `host`, or null when there is none.
+     *
+     * A file that exists but is unreadable or corrupt is a precondition failure,
+     * not a silent "logged out": treating a corrupt file as absent would send the
+     * user through a fresh browser login that then overwrites whatever was
+     * really in there.
+     */
+    read(host: string): StoredSession | null;
+    /** Every host with a stored session. Used by `logout --all` and diagnostics. */
+    hosts(): string[];
+    write(host: string, session: StoredSession): void;
+    /**
+     * Remove the session for `host`. Returns whether anything was removed, so
+     * `logout` can report accurately while still exiting 0 either way — logging
+     * out twice is not an error.
+     */
+    clear(host: string): boolean;
+    /** Remove every session. Returns the number of hosts cleared. */
+    clearAll(): number;
+    private load;
+    /**
+     * Write atomically, and never through a mode the umask can widen.
+     *
+     * `writeFileSync`'s `mode` applies only when the file is CREATED, so a
+     * pre-existing world-readable file would keep its mode on every subsequent
+     * write. Writing a fresh temp file and renaming over the target sidesteps
+     * that, and also means a crash mid-write cannot leave a half-written
+     * credentials file behind.
+     */
+    private persist;
+    /**
+     * Create `~/.ekanos` at 0700 — and repair it if it already exists wider.
+     *
+     * A pre-existing directory is the common case (other Ekanos state may live
+     * there), and `mkdir`'s mode is ignored when the directory is already
+     * present, so the mode has to be asserted separately every time.
+     */
+    private ensureDir;
+    /**
+     * Warn about and repair an over-permissive credentials file.
+     *
+     * Repair rather than refuse: a hard refusal (ssh's behaviour) would leave a
+     * partner with a CLI that will not run and no obvious fix, and the token is
+     * already exposed by the time we notice — narrowing the window beats
+     * blocking. The warning goes to stderr so `--json` stdout stays parseable.
+     */
+    private auditPermissions;
+}
+/**
+ * Resolve the home directory the store lives under. `EKANOS_HOME` exists for
+ * containers and CI, where `os.homedir()` can resolve to a non-writable path.
+ */
+export declare function resolveEkanosHome(env?: Record<string, string | undefined>): string;
+/**
+ * Canonical key for a host: scheme + authority, no trailing slash, lowercased.
+ * Without this, `https://app.example.com` and `https://app.example.com/` would
+ * be two different sessions.
+ */
+export declare function normalizeHost(host: string): string;
+/** A printable summary of a session — never includes a token. */
+export declare function describe(session: StoredSession): {
+    userId: string;
+    email: string | null;
+    expiresAt: string;
+    updatedAt: string;
+};