kennel 0.1.8 → 0.2.0

package/README.md

@@ -1,8 +1,6 @@
-# Kennel CLI
+# Kennel Platform CLI
 
-Schema-backed folder ledger validator for structured workspaces.
-
-Kennel keeps structured folders easy to inspect and validate. It looks upward from the target path for the nearest `schema.json` or `_schema.json`, then validates schema-declared YAML files or Markdown frontmatter documents.
+Publishing, MCP generation, and knowledge-source commands for Kennel workspaces. The compact schema validator has moved to the private [`raggle-ai/kennel-compact`](https://github.com/raggle-ai/kennel-compact) repository.
 
 ## Usage
 
@@ -12,42 +10,97 @@ npm test
 node bin/kennel.mjs --help
 ```
 
-Install locally from this checkout:
-
-```bash
-npm install /Users/andrew/Documents/GitHub/kennel/cli
-kennel --help
-```
-
-Install from npm after publication:
+Install from npm:
 
 ```bash
 npm install --global kennel
 kennel --help
 ```
 
-Publish to npm:
+Run platform commands:
 
 ```bash
-cd /Users/andrew/Documents/GitHub/kennel/cli
-npm publish --access public --registry=https://registry.npmjs.org
-```
-
-Run against folder schemas:
-
-```bash
-kennel schema clients/reapit
-kennel validate clients
-kennel validate projects
-kennel validate partners
-kennel doctor clients/reapit
-kennel dev /Users/andrewmagu/src/cdp-index --config index.json
+kennel pop plan.md --watch
+kennel pop artifacts/pricing-card.html --lan
+kennel view /path/to/workspace
+kennel serve /path/to/workspace
+kennel dev /path/to/docs-site --config index.json
+kennel init .
+kennel core-folders .
+kennel mcp generate . --config index.json
 kennel publish init cloudflare .
 kennel deploy .
 kennel dp .
 ```
 
-Kennel does not create schemas or new records. Manage `schema.json` or `_schema.json` files and folder templates outside the CLI, then use Kennel to inspect and validate them.
+`kennel pop <file>` is the pop-up preview: it starts the static viewer rooted at
+the file's folder, prints a clickable `/folder/<id>/document/<id>` URL, and
+opens it in the default pop-up window. Markdown, HTML artifacts, text, images,
+code, CSV/TSV tables, and `.eml` files are recognized by extension; images and
+binary files are served through `/api/raw`. `--watch` makes the pop-up refresh
+on save (the URL carries `?watch=1`). Folder mode (`--lan`/`--tailscale`)
+prints a phone-accessible link instead.
+
+Document previews are responsive: phones get an edge-to-edge document view and
+≥44px touch targets; `?embedded=1` forces edge-to-edge on desktop; `?panel=1`
+additionally activates the chat side-panel bridge (the generic origin-checked
+`kennel:` postMessage protocol for close/resize/selection). The document header offers Share preview, Copy link, and Download, and
+only shows server-hosted actions (Edit/Open, AI/ACP) when `/api/capabilities`
+says the server provides them.
+
+Remote bindings (`--lan`, `--tailscale`, explicit non-loopback `--host`) are
+secure by design: every `path=` is scoped to the real viewer root, host-action
+endpoints (`/api/open-path`, `/api/open-folder`) return 403, ACP sessions are
+disabled, HTML is never streamed inline from `/api/raw`, and mutation POSTs
+require a same-origin `Origin`/`Referer`. The default host stays `127.0.0.1`.
+
+### Localhost convention (one viewer on port 5180)
+
+Kennel can keep one always-running localhost viewer at
+`http://127.0.0.1:5180`. `knl view <folder>` and `knl pop <file>` default to
+port 5180 and **reuse** that running viewer (`/api/health` check + lock file in
+`$TMPDIR`, see `packages/preview/src/hot-viewer.ts`) instead of starting a
+second one. A separate server is expected only for remote access —
+`kennel share` (LAN), `--tailscale`, or a Cloudflare tunnel — and only on
+explicit request.
+
+Entity search reads allowed local roots from
+`$XDG_CONFIG_HOME/kennel/config.json`, or `~/.config/kennel/config.json` when
+`XDG_CONFIG_HOME` is unset:
+
+```json
+{
+  "allowedRoots": ["/path/to/workspace"]
+}
+```
+
+When this file is absent, entity search allows only the workspace opened by
+`knl`. Invalid config fails closed.
+
+Suggested convention for agents: write generated HTML components to
+`.kennel/preview/<name>.html` and pop them with `knl pop
+.kennel/preview/<name>.html --watch` (reuses 5180), so preview items share one
+well-known scratch folder across any AI client.
+
+`kennel init` scaffolds starter content files for the folder plugins into
+the current folder (or the given path): `todo.json` for Tasks and
+`calendar.json` for Calendar, each referencing its published schema and
+passing the plugin's validation immediately. Existing files are left
+untouched; `--plugin <id>` scaffolds one plugin, `--force` overwrites, and
+`--list` prints what would be created without writing.
+
+`kennel core-folders` lists schema-declared collections and their records using
+the same metadata index as the UI. Titles, icons, counts, fields and validation
+diagnostics come from the declared schema and Markdown frontmatter. Pass
+`--json` for collection/record IDs, revisions and metadata instead of the human
+list. See [Core folders and metadata indexing](../docs/core-folders.md) for
+patterns, parser support, navigation labels and refresh semantics.
+
+`kennel view` starts the source Vite viewer from a Kennel checkout. React and
+CSS changes use HMR. Changes to schema and content files cause a metadata
+refetch without a full page reload. `kennel serve` starts the packaged static
+viewer. The hot viewer uses the current directory when no folder is given. It
+also reuses a Kennel Vite server that already runs on the selected port.
 
 `kennel publish init cloudflare` is the exception for deploy wiring: it scaffolds
 a Cloudflare Worker email-code gate for an existing docs workspace by writing
@@ -67,66 +120,6 @@ Kennel loads `CLOUDFLARE_API_TOKEN` from Doppler only for the publish command.
 `kennel publish cloudflare` remains available when the provider should be
 explicit.
 
-## Folder Shape
-
-```text
-clients/
-  schema.json
-  example-client/
-    client.yml
-    people/
-    notes/
-    comms/
-    evidence/
-```
-
-The nearest parent `schema.json` or `_schema.json` owns the expected shape for folders below it. When both names exist in the same folder, `schema.json` is preferred.
-
-`kennel validate` discovers files from the nearest schema's `x-kennel.documents` declaration. If a schema omits that declaration, Kennel keeps the compatibility default of `client.yml` and `index.md`.
-
-Markdown files are validated using YAML frontmatter. YAML files are parsed as YAML.
-
-## Folder Requirements
-
-Schemas can include a Kennel-only extension for folder shape checks:
-
-```json
-{
-  "x-kennel": {
-    "documents": [
-      "client.yml",
-      { "path": "index.md", "parser": "markdown-frontmatter" },
-      { "glob": "*.yml", "parser": "yaml" }
-    ],
-    "requiredDirectories": ["people", "notes", "comms", "evidence"],
-    "requiredFiles": ["README.md"],
-    "directoryContents": [
-      {
-        "path": "people",
-        "glob": "*.md",
-        "minFiles": 1,
-        "whenPointerMinItems": "/contacts"
-      }
-    ],
-    "fileReferences": [
-      {
-        "pointer": "/contacts/*/path",
-        "required": true,
-        "whenPointerMinItems": "/contacts"
-      }
-    ]
-  }
-}
-```
-
-String document entries match a file name anywhere under the schema root. Object entries can use `path` or `glob` plus an optional parser.
-
-`requiredDirectories` and `requiredFiles` are checked next to each validated document and by `kennel doctor`.
-
-`directoryContents` checks that a sibling directory contains enough matching files. Use `whenPointerMinItems` to apply the rule only when an array in the document is non-empty, or `whenPointerIn` with `{ "pointer": "/client/status", "values": ["active-client"] }` to apply it for selected field values.
-
-`fileReferences` checks that document path fields point to existing files under the same folder. It supports JSON pointers with `*` wildcards, such as `/contacts/*/path`.
-
 ## MCP Analytics
 
 Generated MCP runtimes can emit tool-call metadata and explicit conversation snapshots to analytics providers. Use `mcp.analytics.provider` for one provider, or `mcp.analytics.providers` to fan out to multiple providers:
@@ -138,7 +131,7 @@ Generated MCP runtimes can emit tool-call metadata and explicit conversation sna
       "enabled": true,
       "providers": ["raggle", "posthog", "langfuse"],
       "raggle": {
-        "projectId": "cdp-index",
+        "projectId": "docs-site",
         "apiTokenEnv": "RAGGLE_OTEL_API_TOKEN"
       },
       "posthog": {
@@ -158,7 +151,7 @@ The Raggle provider uses the `raggle-otel` package and defaults to `RAGGLE_OTEL_
 
 ## MCP Repo Integrations
 
-`kennel mcp generate` also emits an MCP server runtime (`@raggle-ai/kennel-mcp`) with core tools for searching index docs and tracked repositories. The runtime additionally exposes repo integration tools that let an agent run basic GitHub or GitLab commands against a repository linked from the index registry (`repos/index.yaml`):
+`kennel mcp generate` also emits an MCP server runtime from `@raggle-ai/kennel/mcp` with core tools for searching index docs and tracked repositories. The runtime additionally exposes repo integration tools that let an agent run basic GitHub or GitLab commands against a repository linked from the index registry (`repos/index.yaml`):
 
 - `submit_repo_feature_request` — open a feature request issue on a tracked repo, submitted on behalf of a user.
 - `list_repo_issues` — list recent issues on a tracked repo.
@@ -174,14 +167,14 @@ To let people supply their own GitHub or GitLab setup (custom token env, self-ho
     "repoIntegrations": {
       "enabled": true,
       "github": {
-        "tokenEnv": "CDP_INDEX_GITHUB_TOKEN",
+        "tokenEnv": "EXAMPLE_DOCS_GITHUB_TOKEN",
         "apiBaseUrl": "https://github.example.com/api/v3"
       },
       "gitlab": {
-        "tokenEnv": "CDP_INDEX_GITLAB_TOKEN",
+        "tokenEnv": "EXAMPLE_DOCS_GITLAB_TOKEN",
         "apiBaseUrl": "https://gitlab.example.com/api/v4"
       },
-      "allowedRepos": ["cdp-index", "index"],
+      "allowedRepos": ["docs-site", "index"],
       "defaultLabels": ["feature-request"]
     }
   }
@@ -190,14 +183,44 @@ To let people supply their own GitHub or GitLab setup (custom token env, self-ho
 
 `allowedRepos` is an optional allowlist of registry repo names; when omitted, every registry repo is available. Set `enabled: false` to disable the repo integration tools while keeping the rest of the MCP server active.
 
+## MCP Tool Catalog Profiles
+
+Large MCP servers can expose a small eager tool surface while keeping specialised tools discoverable. Add `mcp.toolCatalog` to select a default profile. Tools not selected as eager are deferred automatically; `search_index_tools`, `describe_index_tool`, and `call_index_tool` let an agent discover a deferred schema and invoke it through the catalog dispatcher.
+
+```json
+{
+  "mcp": {
+    "toolCatalog": {
+      "defaultProfile": "minimal",
+      "allowClientProfile": true,
+      "profiles": {
+        "minimal": {
+          "eagerTools": [
+            "search_index",
+            "search_index_tools",
+            "describe_index_tool",
+            "call_index_tool"
+          ]
+        },
+        "complete": {
+          "eagerNamespaces": ["*"]
+        }
+      }
+    }
+  }
+}
+```
+
+When `allowClientProfile` is enabled, an MCP client or gateway can select a configured view with the `x-kennel-mcp-profile` header. Profile selection only narrows catalog exposure: role checks and mutating-tool policy still run for direct and dispatched calls. If `toolCatalog` is omitted, the runtime retains the legacy behavior and lists every available tool.
+
 Registry entries that should support issue creation need a `url` (and optionally `provider`):
 
 ```yaml
 repos:
   - name: index
-    url: https://github.com/bakerstreetco/index
+    url: https://github.com/example/index
     provider: github
-  - name: cdp-index
-    url: https://gitlab.com/baker-street/cdp-index
+  - name: docs-site
+    url: https://gitlab.com/example/docs-site
     provider: gitlab
 ```

package/bin/kennel-native.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { extensionHost } from '../dist/site/extension.js';
+
+extensionHost();

package/dist/cli/dispatch.js

@@ -1,51 +1,116 @@
-import { deploy, publish } from '../deploy/cloudflare.js';
-import { generateMcp } from '../mcp/generate.js';
-import { doctor } from '../schema/doctor.js';
-import { schemaFor, validateTarget } from '../schema/validation.js';
-import { dev } from '../site/dev.js';
-import { publishInitCloudflare } from '../publish/cloudflare-init.js';
+import { existsSync } from 'node:fs';
 import { usage } from './usage.js';
 export async function dispatch(argv) {
     const [, , command, ...args] = argv;
-    if (!command || command === '-h' || command === '--help') {
+    if (command === '-h' || command === '--help') {
         usage();
         return;
     }
-    if (command === 'schema') {
-        schemaFor(args[0] ?? '.');
+    if (!command) {
+        const { viewer } = await import('../site/viewer.js');
+        await viewer([]);
         return;
     }
-    if (command === 'validate') {
-        const valid = validateTarget(args[0] ?? '.');
-        process.exit(valid ? 0 : 1);
+    if (command === 'core') {
+        const { core } = await import('../core/command.js');
+        await core(args);
+        return;
+    }
+    if (command === 'init') {
+        const { init } = await import('../core/init.js');
+        await init(args);
+        return;
+    }
+    if (command === 'core-folders') {
+        const { coreFolders } = await import('../core/core-folders.js');
+        await coreFolders(args);
+        return;
+    }
+    if (command === 'view') {
+        const { viewer } = await import('../site/viewer.js');
+        await viewer(['--hot', ...args]);
+        return;
+    }
+    if (command === 'pop' || command === 'p') {
+        const { viewer } = await import('../site/viewer.js');
+        // Single-file pop. Prints a clickable URL; pass --open to open the
+        // default browser (never automatic — agents would stack tabs).
+        await viewer([...args]);
+        return;
+    }
+    if (command === 'open' || command === 'o') {
+        const { viewer } = await import('../site/viewer.js');
+        // Hot viewer. Prints a clickable URL; pass --open to open the browser.
+        await viewer(['--hot', ...args]);
+        return;
     }
-    if (command === 'doctor') {
-        doctor(args[0] ?? '.');
+    if (command === 'mail') {
+        const { mail } = await import('../site/mail.js');
+        await mail(args);
+        return;
+    }
+    if (command === 'serve') {
+        const { viewer } = await import('../site/viewer.js');
+        await viewer(['--static', ...args]);
+        return;
+    }
+    if (command === 'share') {
+        // Deliberate remote share (LAN default; --tailscale for outside the
+        // house). Runs a second remote-scoped static server; the plain 5180
+        // viewer stays loopback-only.
+        const { share } = await import('../package/preview.js');
+        await share(args);
         return;
     }
     if (command === 'dev') {
+        const { dev } = await import('../site/dev.js');
         dev(args);
         return;
     }
+    if (command === 'extension' && args[0] === 'install') {
+        const { extensionInstall } = await import('../site/extension.js');
+        await extensionInstall();
+        return;
+    }
     if (command === 'mcp' && args[0] === 'generate') {
+        const { generateMcp } = await import('../mcp/generate.js');
         await generateMcp(args.slice(1));
         return;
     }
     if (command === 'publish' && args[0] === 'init' && args[1] === 'cloudflare') {
+        const { publishInitCloudflare } = await import('../publish/cloudflare-init.js');
         publishInitCloudflare(args.slice(2));
         return;
     }
+    if (command === 'publish' && args[0] === 'init' && args[1] === 'vercel') {
+        const { publishInitVercel } = await import('../publish/vercel-init.js');
+        publishInitVercel(args.slice(2));
+        return;
+    }
     if (command === 'publish') {
+        const { publish } = await import('../deploy/cloudflare.js');
         publish(args);
         return;
     }
     if (command === 'deploy') {
+        const { deploy } = await import('../deploy/cloudflare.js');
         deploy(args);
         return;
     }
     if (command === 'dp') {
+        const { deploy } = await import('../deploy/cloudflare.js');
         deploy(args);
         return;
     }
-    throw new Error(`Unknown command: ${command}`);
+    // Positionals that are flags or existing paths still go straight to the
+    // viewer (`kennel [folder]`, `kennel note.md`, `kennel --lan .`). Unknown
+    // command words fail loudly instead of silently opening a viewer.
+    if (command.startsWith('-') || existsSync(command)) {
+        const { viewer } = await import('../site/viewer.js');
+        await viewer([command, ...args]);
+        return;
+    }
+    console.error(`Unknown command: ${command}\n`);
+    usage();
+    process.exitCode = 1;
 }

package/dist/cli/usage.js

@@ -1,13 +1,23 @@
 export function usage() {
     console.log(`Usage:
-  kennel schema <path>
-  kennel validate <path>
-  kennel doctor <path>
+  knl core [folder] [--host <host>] [--port <port>] [--api-only]
+  kennel init [path] [--plugin <id>] [--force] [--list]
+  kennel core-folders [path] [--json]
+  kennel [folder] [--host <host>] [--port <port>] [--lan|--tailscale]
+  kennel pop|p <file|folder> [--open] [--watch] [--host <host>] [--port <port>] [--lan|--tailscale]
+  kennel view [folder] [--host <host>] [--port <port>] [--dry-run]
+  kennel open|o [folder] [--open] [--host <host>] [--port <port>] [--dry-run]
+  kennel mail [folder] [--open] [--host <host>] [--port <port>] [--dry-run]
+  kennel serve [folder] [--host <host>] [--port <port>] [--lan|--tailscale]
+  kennel share [folder] [--lan|--tailscale] [--port <port>] [--dry-run]
   kennel dev [path] [--config <json-file>] [--port <port>] [--script <script>] [--dry-run] [-- <args...>]
+  kennel extension install
   kennel mcp generate [path] [--config <json-file>] [--data-only|--function-only]
   kennel publish init cloudflare [path] [--config <json-file>] [--force] [--hostname <hostname>]
+  kennel publish init vercel [path] [--config <json-file>] [--force] [--hostname <hostname>]
   kennel publish [path] [--config <json-file>] [--dry-run] [--force] [--hostname <hostname>] [--test-email <email>] [--skip-test] [--use-doppler-token]
   kennel publish cloudflare [path] [--config <json-file>] [--dry-run] [--force] [--hostname <hostname>] [--test-email <email>] [--skip-test] [--use-doppler-token]
+  kennel publish vercel [path] [--config <json-file>] [--dry-run] [--force] [--hostname <hostname>] [--skip-test]
   kennel deploy [path] [--config <json-file>] [legacy alias for publish]
   kennel dp [path] [--config <json-file>] [legacy alias for publish]
 `);

package/dist/core/api-client.d.ts

@@ -0,0 +1,13 @@
+/** Replaced at build time by the Node bundle of packages/api-client/src/index.ts. */
+import type { operations } from '../../../packages/api-client/src/generated.js';
+type JsonResponse<K extends 'health' | 'documents'> = operations[K]['responses'][200]['content']['application/json'];
+type RequestOptions = {
+    signal?: AbortSignal;
+};
+export declare function createKennelClient(options: {
+    baseUrl: string;
+}): {
+    health(options?: RequestOptions): Promise<JsonResponse<'health'>>;
+    documents(href: string, options?: RequestOptions): Promise<JsonResponse<'documents'>>;
+};
+export {};