kozou 0.1.0 → 0.2.0

package/README.md

@@ -21,7 +21,7 @@ npx -p kozou create-kozou my-project
 
 The package publishes through `./dist/`. `bin` exposes two entries:
 
-- `kozou` - the main multi-command CLI (`inspect` / `mcp` / `dev`)
+- `kozou` - the main multi-command CLI (`inspect` / `docs` / `mcp` / `dev`)
 - `create-kozou` - scaffolds a project directory with
   `docker-compose.yml`, `kozou.config.yaml`, `ui-hints.yaml`,
   `env.example`, and a starter migration
@@ -38,6 +38,16 @@ DATABASE_URL=postgres://kozou:kozou@localhost:5432/kozou \
   kozou inspect --format yaml > schema.yaml
 ```
 
+### `kozou docs`
+
+Generates a single Markdown schema document from the database DDL +
+`COMMENT` metadata to stdout (or `--output <path>`):
+
+```bash
+DATABASE_URL=postgres://kozou:kozou@localhost:5432/kozou \
+  kozou docs --output schema.md
+```
+
 ### `kozou mcp --stdio`
 
 Starts an MCP server over stdio so Claude Code / other AI agents
@@ -50,17 +60,20 @@ DATABASE_URL=postgres://kozou:kozou@localhost:5432/kozou \
 
 The `${DATABASE_URL}` placeholder inside the bundled
 `kozou.config.yaml` template is what consumes that env var; the
-CLI does not honor `KOZOU_DATABASE_URL` directly (an alias is on
-the v0.1.1 roadmap). HTTP transport (`--http`) is also reserved
-for v0.1.1.
+`kozou` CLI does not honor `KOZOU_DATABASE_URL` directly (an alias
+is on the roadmap). HTTP transport is available via
+`kozou mcp --http` (`--port` / `--host` configure the listener;
+stdio stays the default).
 
 ### `kozou dev`
 
-Reserved for v0.1.1. In v0.1.0 the command prints a hand-off
-message listing the subcommands available today
-(`kozou mcp --stdio`, `kozou inspect`) and exits. In v0.1.1 it
-will spawn the bundled `@kozou/svelte-ui` Admin UI + an MCP HTTP
-server.
+Runs the bundled `@kozou/svelte-ui` Admin UI (adapter-node)
+alongside an MCP HTTP server, both wired up from
+`kozou.config.yaml`. The Admin UI listens on port 3333 and the MCP
+HTTP server on 3334 by default (override via `server.ui` /
+`server.mcp.http` in the config); `Ctrl-C` (SIGINT / SIGTERM)
+tears both down. This is the command behind the `kozou` service in
+the scaffolded `docker-compose.yml`.
 
 ### `create-kozou <dir>`
 
@@ -74,11 +87,9 @@ cp .env.example .env
 docker compose up
 ```
 
-The generated `docker-compose.yml` brings up PostgreSQL + PostgREST.
-The `kozou` service block (which would host the Admin UI + MCP HTTP
-server) is commented out in v0.1.0; it gets reactivated in v0.1.1
-once `kozou dev` ships as a real implementation rather than a
-hand-off placeholder.
+The generated `docker-compose.yml` brings up PostgreSQL, PostgREST,
+and a `kozou` service that runs `kozou dev` to host the Admin UI +
+MCP HTTP server.
 
 ## Configuration
 
@@ -104,6 +115,66 @@ The full schema also accepts `server.ui.{port,host}`,
 `create-kozou` writes. `${VAR}` and `${VAR:-default}` are
 expanded from the process environment at load time.
 
+### Authentication (experimental, `--adapter api`)
+
+> **Source-checkout only.** The in-house `@kozou/api` backend is
+> experimental and not yet published to npm, so `kozou dev --adapter api`
+> works only from a source/workspace checkout of this repository. An
+> npm-installed `kozou` does not bundle `@kozou/api`; requesting
+> `--adapter api` there exits with an explicit error. The default
+> `kozou dev` (PostgREST adapter) is unaffected.
+
+By default the in-house `@kozou/api` backend (`kozou dev --adapter api`)
+runs **unauthenticated** on loopback. Add an `auth` section to require a
+signed JWT on every API request: kozou verifies the token, then runs each
+request under `SET LOCAL ROLE <role-from-claim>` with the claims published
+to PostgreSQL, so **your own row-level-security policies** decide what each
+request can read and write.
+
+```yaml
+auth:
+  jwt:
+    secret: ${KOZOU_JWT_SECRET}        # HS256 — or publicKey (RS256), or jwksUri
+    # publicKey: ${KOZOU_JWT_PUBLIC_KEY}
+    # jwksUri: https://your-idp/.well-known/jwks.json  # Auth0 / Clerk / Supabase
+    algorithms: [HS256]
+    issuer: my-issuer                  # optional
+    audience: my-api                   # optional
+  roleClaim: role                      # claim naming the DB role (default: role)
+  allowedRoles: [app_reader, app_admin] # only these roles may be assumed
+  defaultRole: app_reader              # role when the token omits roleClaim
+  anonRole: web_anon                   # role for requests with no token (else 401)
+  ui:
+    role: app_admin                    # role the bundled Admin UI runs as (HS256)
+    # token: ${KOZOU_ADAPTER_TOKEN}    # RS256 / external IdP: supply a token instead
+```
+
+Provide exactly one of `jwt.secret` (HS256), `jwt.publicKey` (RS256), or
+`jwt.jwksUri` (a provider's remote JWKS endpoint — keys are selected by `kid`,
+cached, and refreshed on rotation).
+
+With no `auth:` block, the section is built instead from
+`KOZOU_JWT_SECRET` / `KOZOU_JWT_PUBLIC_KEY` / `KOZOU_JWT_JWKS_URI` /
+`KOZOU_JWT_ALGORITHMS` / `KOZOU_JWT_ISSUER` / `KOZOU_JWT_AUDIENCE` /
+`KOZOU_JWT_ROLE_CLAIM` / `KOZOU_JWT_ALLOWED_ROLES` / `KOZOU_JWT_DEFAULT_ROLE` /
+`KOZOU_JWT_ANON_ROLE` / `KOZOU_UI_ROLE` / `KOZOU_ADAPTER_TOKEN` (algorithms
+and roles are comma-separated). A role outside `allowedRoles` gets `403`. A request with
+no token gets `401` unless `anonRole` is set, in which case it runs under
+that role and your RLS policies decide what it sees (a present but invalid
+token is always `401`). The login role of `database.url` must be `GRANT`ed
+membership in every allowed role, and in `anonRole` when set.
+
+#### The bundled Admin UI
+
+The Admin UI calls `@kozou/api` server-side, so when `auth` is on it must
+send a token too. Under **HS256** the CLI mints one for the UI claiming
+`auth.ui.role` (or, if unset, no role — the API then applies `defaultRole`);
+set `auth.ui.role` to the role the console should run as. Under **RS256**
+or an external identity provider the CLI cannot mint, so supply a
+ready-made token via `auth.ui.token` (or the `KOZOU_ADAPTER_TOKEN` env);
+without it the UI is rejected with `401` and the CLI logs how to fix it.
+The minted role must satisfy `allowedRoles` or the UI gets `403`.
+
 ## License
 
 Apache 2.0. See [LICENSE](../../LICENSE) at the repository root.

package/dist/cli.js

@@ -3,6 +3,8 @@
 // Kozou v0.1 design spec §9.1 via commander.
 import { Command } from 'commander';
 import { inspectCommand } from './commands/inspect.js';
+import { codegenCommand } from './commands/codegen.js';
+import { docsCommand } from './commands/docs.js';
 import { mcpCommand } from './commands/mcp.js';
 import { devCommand } from './commands/dev.js';
 import { PACKAGE_VERSION } from './index.js';
@@ -23,27 +25,57 @@ program
         config: flags.config,
     });
 });
+program
+    .command('codegen')
+    .description('Generate TypeScript row types from the database schema (experimental).')
+    .option('--output <path>', 'output file (- for stdout)', '-')
+    .option('--config <path>', 'path to kozou.config.yaml')
+    .action(async (flags) => {
+    await codegenCommand({
+        output: flags.output,
+        config: flags.config,
+    });
+});
+program
+    .command('docs')
+    .description('Generate a Markdown schema document from the database DDL + COMMENT.')
+    .option('--output <path>', 'output file (- for stdout)', '-')
+    .option('--config <path>', 'path to kozou.config.yaml')
+    .action(async (flags) => {
+    await docsCommand({
+        output: flags.output,
+        config: flags.config,
+    });
+});
 program
     .command('mcp')
-    .description('Run the MCP server (stdio in v0.1; HTTP in v0.1.1).')
+    .description('Run the MCP server (--stdio default, or --http).')
     .option('--stdio', 'use stdio transport (default)')
-    .option('--http', 'use HTTP transport (scheduled for v0.1.1)')
-    .option('--port <n>', 'HTTP port', (raw) => parseInt(raw, 10))
+    .option('--http', 'use Streamable HTTP transport')
+    .option('--port <n>', 'HTTP port (default 3334)', (raw) => parseInt(raw, 10))
+    .option('--host <host>', 'HTTP bind host (default 127.0.0.1)')
     .option('--config <path>', 'path to kozou.config.yaml')
     .action(async (flags) => {
     await mcpCommand({
         stdio: flags.stdio,
         http: flags.http,
         port: flags.port,
+        host: flags.host,
         config: flags.config,
     });
 });
 program
     .command('dev')
-    .description('Run the bundled Admin UI + MCP HTTP dev server (v0.1.1).')
+    .description('Run the bundled Admin UI + MCP HTTP dev server.')
     .option('--config <path>', 'path to kozou.config.yaml')
+    .option('--adapter <kind>', 'set to "api" for the experimental in-house @kozou/api backend (default: the bundled REST adapter)')
+    .option('--api-port <n>', 'port for the in-house @kozou/api server (with --adapter api)', (raw) => parseInt(raw, 10))
     .action(async (flags) => {
-    await devCommand({ config: flags.config });
+    await devCommand({
+        config: flags.config,
+        adapter: flags.adapter,
+        apiPort: flags.apiPort,
+    });
 });
 program.parseAsync(process.argv).catch((err) => {
     process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,gEAAgE;AAChE,6CAA6C;AAE7C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAmB7C,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE;KAC1B,IAAI,CAAC,OAAO,CAAC;KACb,WAAW,CACV,mFAAmF,CACpF;KACA,OAAO,CAAC,eAAe,CAAC,CAAC;AAE5B,OAAO;KACJ,OAAO,CAAC,SAAS,CAAC;KAClB,WAAW,CAAC,0CAA0C,CAAC;KACvD,MAAM,CAAC,gBAAgB,EAAE,4BAA4B,EAAE,MAAM,CAAC;KAC9D,MAAM,CAAC,iBAAiB,EAAE,4BAA4B,EAAE,GAAG,CAAC;KAC5D,MAAM,CAAC,iBAAiB,EAAE,2BAA2B,CAAC;KACtD,MAAM,CAAC,KAAK,EAAE,KAAmB,EAAE,EAAE;IACpC,MAAM,cAAc,CAAC;QACnB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,MAAM,EAAE,KAAK,CAAC,MAAM;KACrB,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEL,OAAO;KACJ,OAAO,CAAC,KAAK,CAAC;KACd,WAAW,CAAC,qDAAqD,CAAC;KAClE,MAAM,CAAC,SAAS,EAAE,+BAA+B,CAAC;KAClD,MAAM,CAAC,QAAQ,EAAE,2CAA2C,CAAC;KAC7D,MAAM,CAAC,YAAY,EAAE,WAAW,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;KAC7D,MAAM,CAAC,iBAAiB,EAAE,2BAA2B,CAAC;KACtD,MAAM,CAAC,KAAK,EAAE,KAAe,EAAE,EAAE;IAChC,MAAM,UAAU,CAAC;QACf,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,MAAM,EAAE,KAAK,CAAC,MAAM;KACrB,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEL,OAAO;KACJ,OAAO,CAAC,KAAK,CAAC;KACd,WAAW,CAAC,0DAA0D,CAAC;KACvE,MAAM,CAAC,iBAAiB,EAAE,2BAA2B,CAAC;KACtD,MAAM,CAAC,KAAK,EAAE,KAAe,EAAE,EAAE;IAChC,MAAM,UAAU,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;AAC7C,CAAC,CAAC,CAAC;AAEL,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IAC7C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9E,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/commands/codegen.d.ts

@@ -0,0 +1,8 @@
+export type CodegenOptions = {
+    /** Output destination. '-' = stdout (default), otherwise a file path. */
+    output?: string;
+    /** Path to kozou.config.yaml. Default: ./kozou.config.yaml. */
+    config?: string;
+};
+export declare function codegenCommand(opts?: CodegenOptions): Promise<void>;
+//# sourceMappingURL=codegen.d.ts.map

package/dist/commands/codegen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codegen.d.ts","sourceRoot":"","sources":["../../src/commands/codegen.ts"],"names":[],"mappings":"AAsBA,MAAM,MAAM,cAAc,GAAG;IAC3B,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,wBAAsB,cAAc,CAAC,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAwC7E"}

package/dist/commands/codegen.js

@@ -0,0 +1,54 @@
+// `kozou codegen` command implementation.
+//
+// Pipeline (mirrors `kozou inspect`):
+//   1. Load the kozou.config.yaml (or fall back to defaults).
+//   2. Introspect the target Postgres schema (@kozou/introspect).
+//   3. Optionally load UI hints (@kozou/core.loadUIHints).
+//   4. Build a SchemaContext (@kozou/core.buildSchemaContext).
+//   5. Emit TypeScript row types (@kozou/codegen) and write them out.
+//
+// @kozou/codegen is an experimental, unpublished workspace package, so it is
+// imported dynamically and is only resolvable from a source / workspace
+// checkout — a published `kozou` install gets a clear error (mirrors the
+// `--adapter api` handling in dev.ts).
+import { writeFile } from 'node:fs/promises';
+import { buildSchemaContext, loadUIHints } from '@kozou/core';
+import { introspect } from '@kozou/introspect';
+import { loadConfig } from '../config.js';
+const PREFIX = '[kozou codegen]';
+export async function codegenCommand(opts = {}) {
+    const output = opts.output ?? '-';
+    let codegenModule;
+    try {
+        codegenModule = await import('@kozou/codegen');
+    }
+    catch {
+        throw new Error(`${PREFIX} needs the experimental @kozou/codegen package, which is not ` +
+            'bundled in this release. Run kozou from a source / workspace checkout to use it.');
+    }
+    const config = await loadConfig({ path: opts.config });
+    const raw = await introspect({
+        connection: config.database.url,
+        schemas: config.database.schemas,
+    });
+    let uiHints;
+    if (config.uiHints.path !== null && config.uiHints.path !== '') {
+        try {
+            uiHints = await loadUIHints(config.uiHints.path);
+        }
+        catch (err) {
+            // UI hints are optional; warn but continue without them.
+            const message = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`${PREFIX} could not load UI hints: ${message}\n`);
+        }
+    }
+    const ctx = await buildSchemaContext({ raw, uiHints });
+    const serialized = codegenModule.emitRowTypes(ctx);
+    const payload = serialized.endsWith('\n') ? serialized : serialized + '\n';
+    if (output === '-') {
+        process.stdout.write(payload);
+        return;
+    }
+    await writeFile(output, payload, 'utf8');
+}
+//# sourceMappingURL=codegen.js.map

package/dist/commands/codegen.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codegen.js","sourceRoot":"","sources":["../../src/commands/codegen.ts"],"names":[],"mappings":"AAAA,0CAA0C;AAC1C,EAAE;AACF,sCAAsC;AACtC,8DAA8D;AAC9D,kEAAkE;AAClE,2DAA2D;AAC3D,+DAA+D;AAC/D,sEAAsE;AACtE,EAAE;AACF,6EAA6E;AAC7E,wEAAwE;AACxE,yEAAyE;AACzE,uCAAuC;AAEvC,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE9D,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C,MAAM,MAAM,GAAG,iBAAiB,CAAC;AASjC,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,OAAuB,EAAE;IAC5D,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,GAAG,CAAC;IAElC,IAAI,aAA8C,CAAC;IACnD,IAAI,CAAC;QACH,aAAa,GAAG,MAAM,MAAM,CAAC,gBAAgB,CAAC,CAAC;IACjD,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CACb,GAAG,MAAM,+DAA+D;YACtE,kFAAkF,CACrF,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IAEvD,MAAM,GAAG,GAAG,MAAM,UAAU,CAAC;QAC3B,UAAU,EAAE,MAAM,CAAC,QAAQ,CAAC,GAAG;QAC/B,OAAO,EAAE,MAAM,CAAC,QAAQ,CAAC,OAAO;KACjC,CAAC,CAAC;IAEH,IAAI,OAA4B,CAAC;IACjC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,KAAK,IAAI,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,KAAK,EAAE,EAAE,CAAC;QAC/D,IAAI,CAAC;YACH,OAAO,GAAG,MAAM,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACnD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,yDAAyD;YACzD,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACjE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,MAAM,6BAA6B,OAAO,IAAI,CAAC,CAAC;QAC1E,CAAC;IACH,CAAC;IAED,MAAM,GAAG,GAAG,MAAM,kBAAkB,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC;IACvD,MAAM,UAAU,GAAG,aAAa,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;IACnD,MAAM,OAAO,GAAG,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,UAAU,GAAG,IAAI,CAAC;IAE3E,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;QACnB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC9B,OAAO;IACT,CAAC;IACD,MAAM,SAAS,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;AAC3C,CAAC"}

package/dist/commands/dev-runtime.d.ts

@@ -0,0 +1,21 @@
+import type { KozouConfig } from '../config.js';
+export declare function resolveAdminUiEntry(): string;
+export declare function resolveOrigin(config: KozouConfig, env: NodeJS.ProcessEnv): string;
+export declare function buildAdminUiEnv(config: KozouConfig, origin: string, baseEnv: NodeJS.ProcessEnv, apiAdapterUrl?: string, apiToken?: string): NodeJS.ProcessEnv;
+export type ServiceTokenMinter = {
+    signServiceToken(opts: {
+        secret: string;
+        roleClaim?: string;
+        role?: string;
+        issuer?: string;
+        audience?: string | string[];
+    }): Promise<string>;
+};
+export type AdminUiTokenResult = {
+    /** Bearer token the Admin UI should send, when one could be obtained. */
+    token?: string;
+    /** Operator-facing reason the UI will be rejected, when no usable token. */
+    warning?: string;
+};
+export declare function resolveAdminUiToken(config: KozouConfig, minter: ServiceTokenMinter, env: NodeJS.ProcessEnv): Promise<AdminUiTokenResult>;
+//# sourceMappingURL=dev-runtime.d.ts.map

package/dist/commands/dev-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-runtime.d.ts","sourceRoot":"","sources":["../../src/commands/dev-runtime.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAOhD,wBAAgB,mBAAmB,IAAI,MAAM,CAI5C;AAMD,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,CAEjF;AAWD,wBAAgB,eAAe,CAC7B,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,CAAC,UAAU,EAC1B,aAAa,CAAC,EAAE,MAAM,EACtB,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM,CAAC,UAAU,CAsBnB;AAID,MAAM,MAAM,kBAAkB,GAAG;IAC/B,gBAAgB,CAAC,IAAI,EAAE;QACrB,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;KAC9B,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAWF,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,kBAAkB,EAC1B,GAAG,EAAE,MAAM,CAAC,UAAU,GACrB,OAAO,CAAC,kBAAkB,CAAC,CA8B7B"}

package/dist/commands/dev-runtime.js

@@ -0,0 +1,111 @@
+// Pure wiring helpers for `kozou dev` (see commands/dev.ts).
+//
+// Kept separate from the spawn / lifecycle shell in dev.ts so the
+// config -> child-process-env / origin / entry-path mapping can be unit
+// tested without launching any servers.
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+// Resolve the Admin UI's adapter-node standalone server entry. The
+// `build/` directory ships in @kozou/svelte-ui's published `files`, and
+// resolving the package's own package.json works whether kozou runs from
+// a flat node_modules tree (Docker / npm install) or a workspace symlink
+// (local dev).
+export function resolveAdminUiEntry() {
+    const require = createRequire(import.meta.url);
+    const pkgJsonPath = require.resolve('@kozou/svelte-ui/package.json');
+    return join(dirname(pkgJsonPath), 'build', 'index.js');
+}
+// The browser-facing origin the Admin UI must accept form posts from.
+// An explicit ORIGIN / KOZOU_ORIGIN wins; otherwise default to localhost
+// on the UI port (host stays 0.0.0.0 for binding, but browsers reach it
+// as localhost in the common single-host case).
+export function resolveOrigin(config, env) {
+    return env.ORIGIN ?? env.KOZOU_ORIGIN ?? `http://localhost:${config.server.ui.port}`;
+}
+// Build the child-process environment for the Admin UI server. Keeping
+// it pure makes the wiring unit-testable without spawning anything.
+//
+// When `apiAdapterUrl` is given (`kozou dev --adapter api`), the UI is
+// pointed at the in-house @kozou/api server via KOZOU_ADAPTER_KIND=api;
+// otherwise it uses the default REST adapter URL from config. On the api
+// path `apiToken` (when present) is exposed as KOZOU_ADAPTER_TOKEN so the
+// UI attaches it as a Bearer token; any inherited value is cleared so a
+// stray env var cannot leak in.
+export function buildAdminUiEnv(config, origin, baseEnv, apiAdapterUrl, apiToken) {
+    const adapter = apiAdapterUrl !== undefined
+        ? { KOZOU_ADAPTER_KIND: 'api', KOZOU_ADAPTER_URL: apiAdapterUrl }
+        : { KOZOU_ADAPTER_URL: config.adapter.url };
+    const env = {
+        ...baseEnv,
+        DATABASE_URL: config.database.url,
+        ...adapter,
+        PORT: String(config.server.ui.port),
+        HOST: config.server.ui.host,
+        ORIGIN: origin,
+        NODE_ENV: 'production',
+    };
+    if (apiAdapterUrl !== undefined) {
+        if (apiToken !== undefined && apiToken.length > 0) {
+            env.KOZOU_ADAPTER_TOKEN = apiToken;
+        }
+        else {
+            delete env.KOZOU_ADAPTER_TOKEN;
+        }
+    }
+    return env;
+}
+// Decide what token (if any) the bundled Admin UI should send to @kozou/api,
+// given the resolved config. Pure except for the injected minter:
+//   (a) an explicit token (auth.ui.token / KOZOU_ADAPTER_TOKEN) is passed
+//       through — the path for RS256 / an external IdP, where the CLI cannot
+//       mint;
+//   (b) otherwise, with an HS256 secret, the CLI mints a token claiming the
+//       configured role (auth.ui.role; absent -> the API's defaultRole);
+//   (c) otherwise (an RS256 key with no supplied token) no token is returned
+//       and a warning explains how to supply one.
+export async function resolveAdminUiToken(config, minter, env) {
+    const auth = config.auth;
+    if (auth === undefined)
+        return {}; // no auth -> the UI sends no token (unchanged)
+    const supplied = auth.ui?.token ?? env.KOZOU_ADAPTER_TOKEN;
+    if (supplied !== undefined && supplied.length > 0) {
+        return { token: supplied };
+    }
+    const secret = auth.jwt.secret;
+    if (secret !== undefined && secret.length > 0) {
+        const role = auth.ui?.role;
+        const token = await minter.signServiceToken({
+            secret,
+            roleClaim: auth.roleClaim,
+            role,
+            issuer: auth.jwt.issuer,
+            audience: auth.jwt.audience,
+        });
+        const warning = mintedRoleWarning(auth, role);
+        return warning !== undefined ? { token, warning } : { token };
+    }
+    return {
+        warning: 'auth uses an RS256 public key, so the CLI cannot mint a token for the ' +
+            'bundled Admin UI; it will be rejected with 401. Set auth.ui.token (or ' +
+            'KOZOU_ADAPTER_TOKEN) to a token from your identity provider, or use an ' +
+            'HS256 secret so the CLI can mint one.',
+    };
+}
+// A minted Admin UI token will be rejected with 403 unless the API can
+// resolve an allowed role for it. Surface that as a warning at startup
+// rather than letting the UI fail opaquely.
+function mintedRoleWarning(auth, role) {
+    const effective = role !== undefined && role.length > 0 ? role : auth.defaultRole;
+    if (effective === undefined || effective.length === 0) {
+        return 'auth.ui.role is unset and no defaultRole is configured, so the ' +
+            'minted Admin UI token carries no role and the API will reject it with ' +
+            '403. Set auth.ui.role to the role the Admin UI should assume.';
+    }
+    if (auth.allowedRoles !== undefined && !auth.allowedRoles.includes(effective)) {
+        return `the Admin UI token's role "${effective}" is not in allowedRoles, so ` +
+            'the API will reject it with 403. Add it to allowedRoles or change ' +
+            'auth.ui.role.';
+    }
+    return undefined;
+}
+//# sourceMappingURL=dev-runtime.js.map

package/dist/commands/dev-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-runtime.js","sourceRoot":"","sources":["../../src/commands/dev-runtime.ts"],"names":[],"mappings":"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"}

package/dist/commands/dev.d.ts

@@ -1,5 +1,9 @@
 export type DevOptions = {
     config?: string;
+    /** Set to 'api' for the experimental in-house @kozou/api backend; omit for the default REST adapter. */
+    adapter?: string;
+    /** Port for the in-house @kozou/api server (used when adapter === 'api'). */
+    apiPort?: number;
 };
-export declare function devCommand(_opts?: DevOptions): Promise<void>;
+export declare function devCommand(opts?: DevOptions): Promise<void>;
 //# sourceMappingURL=dev.d.ts.map

package/dist/commands/dev.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../src/commands/dev.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,UAAU,GAAG;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAeF,wBAAsB,UAAU,CAAC,KAAK,GAAE,UAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAEtE"}
+{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../src/commands/dev.ts"],"names":[],"mappings":"AA+BA,MAAM,MAAM,UAAU,GAAG;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wGAAwG;IACxG,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAwEF,wBAAsB,UAAU,CAAC,IAAI,GAAE,UAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CA+GrE"}