@malmhq/intermesh-cli 0.1.0

package/dist/generation/templates/npm-cli/GENERATION-PATTERNS.md

@@ -0,0 +1,143 @@
+# Generation patterns
+
+This file is generation-only guidance and is not published. Start with your assigned packet and this guide. The runner has created and registered your command, mock and test files. Fill only `writable_paths`; do not edit registration, authentication, shared helpers or the capability manifest.
+
+## Helpers from a command file
+
+- `../shared/http.js`: `request({ baseUrl?, method, path, query?, body?, mediaType?, timeoutMs? })` returns `{ body: Uint8Array, mediaType: string, status: number }`. Use `URLSearchParams` for query values and bytes for request bodies. The packet lists the full signature.
+- Forward `command.optsWithGlobals().baseUrl` to `request`. When absent, the helper uses the customer API and configured credentials. When present, it permits only loopback mocks and sends no credential. Do not build authentication yourself.
+- `../shared/output.js`: `parseJson(body)` preserves large JSON numbers; `printSuccess(data, command)` writes the success envelope. Do not convert exact identifiers through `Number`.
+- `../shared/errors.js`: throw `new CliError(cliErrors.invalidInput(message))` for invalid customer input. `runCli` owns formatting errors and exit codes; the transport owns upstream errors, redirects and header/body timeouts (30 seconds by default).
+- `../shared/files.js`: `await saveFile(path, body, mediaType)` preserves bytes, rejects existing destinations, and returns `{ path, media_type }`.
+- For file-producing commands, call `await validateOutputFile(path)` from the same helper before the first request, so invalid destinations also fail in dry run. `saveFile` rechecks the destination and writes exclusively during execution.
+
+All results, including errors, use a versioned JSON envelope on stdout. Never print credentials or raw request bodies. Commands must validate every locally available input before calling `request`, including parsing input files and checking output destinations. Keep all writes after that call. Non-interactive commands must never prompt.
+
+Every generated command must pass `workflow: { summary, steps }` to its first `request`. Describe the complete intended sequence, including conditional branches, repeated requests and output-file writes. Each step has a plain `summary`; add `depends_on_response: true` when its values or whether it runs depend on a previous response. The helper validates request construction, prints all declared steps and stops before HTTP in dry-run mode. Do not fabricate responses or swallow the completion signal. Keep summaries specific to the selected action but never interpolate secrets, raw input values or file contents. For workflows without HTTP, call `previewWorkflow(workflow, commandName)` from `../shared/dry-run.js` after local validation and before any effects.
+
+Missing files, invalid inputs and existing output files must fail even in dry run. Server permissions, customer existence and response-dependent values remain explicitly unchecked; they do not make an otherwise valid preview fail. Test the real command with `--dry-run`: assert every intended step appears, invalid local inputs fail, and no requests or writes occur. Keep general usage instructions and examples in `--help`.
+
+## Minimal JSON example
+
+Synthetic `records` illustrates the wiring, not customer requirements. Replace its command, flags, validation, path and mock data with your packet's exact requirements. Imports below are relative to the named files.
+
+`src/commands/records.ts`:
+
+```typescript
+import type { Command } from 'commander';
+import { request } from '../shared/http.js';
+import { CliError, cliErrors } from '../shared/errors.js';
+import { parseJson, printSuccess } from '../shared/output.js';
+
+export function register(program: Command): void {
+  program
+    .command('records')
+    .requiredOption('--id <id>', 'Exact decimal identifier', (value: string) => {
+      if (!/^[0-9]+$/.test(value))
+        throw new CliError(cliErrors.invalidInput('ID must be a non-negative integer.'));
+      return value;
+    })
+    .allowExcessArguments(false)
+    .action(async (_options, command) => {
+      const { id, baseUrl } = command.optsWithGlobals() as { id: string; baseUrl?: string };
+      const response = await request({
+        baseUrl,
+        method: 'GET',
+        path: '/records',
+        query: new URLSearchParams({ id }),
+        workflow: {
+          summary: 'Look up the record matching the supplied ID.',
+          steps: [{ summary: 'Fetch the matching record' }],
+        },
+      });
+      printSuccess(parseJson(response.body), 'records');
+    });
+}
+```
+
+`mock/routes/records.ts`:
+
+```typescript
+import type { MockRoute } from '../types.js';
+
+export const routes: MockRoute[] = [
+  {
+    method: 'GET',
+    path: '/records',
+    handle(_url, response) {
+      response.writeHead(200, { 'content-type': 'application/json' });
+      response.end('{"id":9007199254740993}');
+    },
+  },
+];
+```
+
+`test/records.test.ts` — test the real CLI in an asynchronous child process so the mock server can respond:
+
+```typescript
+import assert from 'node:assert/strict';
+import { execFile } from 'node:child_process';
+import { createServer } from 'node:http';
+import { promisify } from 'node:util';
+import test from 'node:test';
+import { routes } from '../mock/routes/records.js';
+
+const exec = promisify(execFile);
+test('records preserves IDs and rejects invalid input before HTTP', async () => {
+  const requests: string[] = [];
+  const server = createServer((request, response) => {
+    requests.push(request.url ?? '');
+    const url = new URL(request.url ?? '/', 'http://127.0.0.1');
+    const route = routes.find(
+      (item) => item.method === request.method && item.path === url.pathname,
+    );
+    if (route) route.handle(url, response);
+    else {
+      response.writeHead(404);
+      response.end();
+    }
+  });
+  await new Promise<void>((ready) => server.listen(0, '127.0.0.1', ready));
+  try {
+    const address = server.address();
+    assert.ok(address && typeof address !== 'string');
+    const run = (args: string[]) =>
+      exec(
+        process.execPath,
+        [
+          '--import',
+          'tsx',
+          'src/index.ts',
+          'records',
+          ...args,
+          '--base-url',
+          `http://127.0.0.1:${address.port}`,
+        ],
+        { timeout: 10_000 },
+      );
+    await assert.rejects(run(['--id', '1junk']), (error) => {
+      assert.equal((error as { code: number }).code, 2);
+      assert.equal(JSON.parse((error as { stdout: string }).stdout).error.code, 'INVALID_INPUT');
+      return true;
+    });
+    assert.equal(requests.length, 0);
+    const result = await run(['--id', '9007199254740993']);
+    assert.equal(result.stderr, '');
+    assert.match(result.stdout, /"id":9007199254740993/);
+    assert.deepEqual(requests, ['/records?id=9007199254740993']);
+  } finally {
+    server.closeAllConnections();
+    await new Promise<void>((done) => server.close(() => done()));
+  }
+});
+```
+
+Run the packet's `focused_check` directly from `package/`, preserving its real exit code. If it fails, repair the affected code or report a blocker. Rerun only after an affected repair or relevant code change. After it passes, move to the next assigned packet; when all assigned packets pass, report results from existing tool output and finish without separate evidence files or a post-pass file review. This example shows the test structure, not complete coverage: add your packet's source-specific cases and required safety checks without duplicating shared-foundation tests.
+
+## Response variations
+
+- JSON: call `request`, parse bytes with `parseJson`, then call `printSuccess`.
+- Text: call `request`, decode bytes as UTF-8, then call `printSuccess`.
+- File: require `--output-file`, call `request`, preserve bytes with `saveFile`, then call `printSuccess` with the returned file metadata.
+
+For text, use `Buffer.from(response.body).toString('utf8')`. For files, pass `response.body` and `response.mediaType` directly to `saveFile`; include source-required identifiers alongside its returned metadata. Do not parse and re-encode file contents. The approved packet decides the response pattern, not this example.

package/dist/generation/templates/npm-cli/README.md

@@ -0,0 +1,67 @@
+# __DISPLAY_NAME__
+
+`__BINARY__` is an agent-ready CLI for the approved capabilities of this API.
+
+## Install
+
+```bash
+npm install --global __PACKAGE_NAME__
+```
+
+## Connect
+
+Create an API token in the customer platform, then store it in your operating system's secure
+credential manager:
+
+```bash
+__BINARY__ login
+__BINARY__ status
+```
+
+The token is entered through a hidden prompt. It is not printed or stored in a plaintext file.
+For CI, set `__ENV__` through the CI provider's secret manager instead of running `login`.
+
+## Install Agent Skills
+
+Install the bundled Skills in the shared Agent Skills directory:
+
+```bash
+__BINARY__ setup --help
+__BINARY__ setup --scope project --project-dir .
+__BINARY__ status
+```
+
+Skill setup and authentication are independent. Status reports both states.
+
+## Use
+
+```bash
+__BINARY__ --help
+```
+
+Read command help before using unfamiliar flags. Customer workflows and verified examples replace
+this section during generation.
+
+## Disconnect
+
+```bash
+__BINARY__ logout
+```
+
+This removes the local credential. It does not revoke the token in the customer platform.
+
+## Update
+
+```bash
+__BINARY__ update --help
+```
+
+Update installs the latest npm package and synchronizes only this CLI's managed Skills.
+
+## Troubleshooting
+
+- `AUTH_REQUIRED`: run `__BINARY__ login` or configure `__ENV__`.
+- `AUTH_FAILED`: replace an expired or revoked token by running `__BINARY__ login` again.
+- `CREDENTIAL_STORE_UNAVAILABLE`: unlock or enable the operating system credential manager.
+
+Development and offline verification instructions are in `CONTRIBUTING.md` in the source repository.

package/dist/generation/templates/npm-cli/capabilities.json

@@ -0,0 +1 @@
+{ "commands": [], "excluded": [] }

package/dist/generation/templates/npm-cli/mock/routes.ts

@@ -0,0 +1,3 @@
+import type { MockRoute } from './types.js';
+
+export const routes: MockRoute[] = [];

package/dist/generation/templates/npm-cli/mock/server.ts

@@ -0,0 +1,15 @@
+import { createServer } from 'node:http';
+import { routes } from './routes.js';
+
+createServer((request, response) => {
+  const url = new URL(request.url ?? '/', 'http://127.0.0.1');
+  const route = routes.find((item) => item.method === request.method && item.path === url.pathname);
+  if (route) {
+    route.handle(url, response);
+    return;
+  }
+  response.writeHead(404, { 'content-type': 'application/json' });
+  response.end('{"message":"No mock route configured"}');
+}).listen(8787, '127.0.0.1', () => {
+  process.stderr.write('Mock listening at http://127.0.0.1:8787\n');
+});

package/dist/generation/templates/npm-cli/mock/types.ts

@@ -0,0 +1,7 @@
+import type { ServerResponse } from 'node:http';
+
+export interface MockRoute {
+  method: string;
+  path: string;
+  handle(url: URL, response: ServerResponse): void;
+}

package/dist/generation/templates/npm-cli/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "customer-cli-starter",
+  "version": "0.1.0",
+  "description": "Agent-ready customer API CLI foundation",
+  "private": true,
+  "type": "module",
+  "bin": {
+    "customer-cli": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md",
+    "capabilities.json"
+  ],
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "tsx --test --test-concurrency=1 test/*.test.ts",
+    "build": "tsc --project tsconfig.build.json && node -e \"require('node:fs').chmodSync('dist/index.js', 0o755)\"",
+    "mock:run": "tsx test/run-with-mock.ts"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "packageManager": "pnpm@11.21.0",
+  "dependencies": {
+    "@napi-rs/keyring": "1.3.0",
+    "commander": "15.0.0",
+    "lossless-json": "4.3.1"
+  },
+  "devDependencies": {
+    "@types/node": "24.13.3",
+    "tsx": "4.20.6",
+    "typescript": "6.0.3"
+  }
+}