@celilo/cli 0.1.4 → 0.1.6

package/src/module/packaging/release-metadata.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, test } from 'bun:test';
+import { type GitCommandRunner, buildReleaseMetadata, collectGitInfo } from './release-metadata';
+
+describe('buildReleaseMetadata', () => {
+  test('produces a stable shape from injected inputs', () => {
+    const meta = buildReleaseMetadata({
+      moduleId: 'caddy',
+      version: '1.2.0+3',
+      git: { sha: 'abc1234', branch: 'main', dirty: false },
+      cliVersion: '0.1.5',
+      message: 'Fix DNS race',
+      publishedAt: new Date('2026-04-25T18:30:00Z'),
+    });
+
+    expect(meta).toEqual({
+      module_id: 'caddy',
+      version: '1.2.0+3',
+      git_sha: 'abc1234',
+      git_branch: 'main',
+      git_dirty: false,
+      published_at: '2026-04-25T18:30:00.000Z',
+      published_by_cli_version: '0.1.5',
+      message: 'Fix DNS race',
+    });
+  });
+
+  test('null message is preserved (no defaulting to empty string)', () => {
+    const meta = buildReleaseMetadata({
+      moduleId: 'x',
+      version: '1.0.0+1',
+      git: { sha: null, branch: null, dirty: false },
+      cliVersion: '0.1.5',
+      message: null,
+      publishedAt: new Date('2026-04-25T00:00:00Z'),
+    });
+    expect(meta.message).toBeNull();
+  });
+
+  test('defaults publishedAt to now when omitted', () => {
+    const before = Date.now();
+    const meta = buildReleaseMetadata({
+      moduleId: 'x',
+      version: '1.0.0+1',
+      git: { sha: null, branch: null, dirty: false },
+      cliVersion: '0.1.5',
+      message: null,
+    });
+    const stamped = new Date(meta.published_at).getTime();
+    expect(stamped).toBeGreaterThanOrEqual(before);
+    expect(stamped).toBeLessThanOrEqual(Date.now());
+  });
+});
+
+describe('collectGitInfo', () => {
+  test('returns nulls + clean when not in a git checkout', () => {
+    const run: GitCommandRunner = () => null;
+    expect(collectGitInfo('/tmp/x', run)).toEqual({
+      sha: null,
+      branch: null,
+      dirty: false,
+    });
+  });
+
+  test('reads sha + branch + clean status', () => {
+    const calls: string[][] = [];
+    const run: GitCommandRunner = (args) => {
+      calls.push(args);
+      if (args[0] === 'rev-parse' && args[1] === 'HEAD') return 'abc1234';
+      if (args[0] === 'rev-parse' && args[1] === '--abbrev-ref') return 'main';
+      if (args[0] === 'status') return '';
+      return null;
+    };
+
+    const info = collectGitInfo('/tmp/x', run);
+
+    expect(info).toEqual({ sha: 'abc1234', branch: 'main', dirty: false });
+    expect(calls).toEqual([
+      ['rev-parse', 'HEAD'],
+      ['rev-parse', '--abbrev-ref', 'HEAD'],
+      ['status', '--porcelain'],
+    ]);
+  });
+
+  test('detached HEAD reports null branch', () => {
+    const run: GitCommandRunner = (args) => {
+      if (args[0] === 'rev-parse' && args[1] === 'HEAD') return 'abc1234';
+      if (args[0] === 'rev-parse' && args[1] === '--abbrev-ref') return 'HEAD';
+      if (args[0] === 'status') return '';
+      return null;
+    };
+    expect(collectGitInfo('/tmp/x', run).branch).toBeNull();
+  });
+
+  test('non-empty status output → dirty=true', () => {
+    const run: GitCommandRunner = (args) => {
+      if (args[0] === 'rev-parse' && args[1] === 'HEAD') return 'abc1234';
+      if (args[0] === 'rev-parse' && args[1] === '--abbrev-ref') return 'main';
+      if (args[0] === 'status') return ' M src/foo.ts\n?? new-file.txt';
+      return null;
+    };
+    expect(collectGitInfo('/tmp/x', run).dirty).toBe(true);
+  });
+});

package/src/module/packaging/release-metadata.ts

@@ -0,0 +1,145 @@
+/**
+ * Release metadata stamped into every .netapp at publish time.
+ *
+ * Per CELILO_UPDATE D5, each published package carries a `release.json`
+ * recording git SHA, branch, dirty flag, publish timestamp, the CLI
+ * version that produced the build, and an optional one-line release
+ * note. `system audit` and `system update` surface this to give the
+ * user a clear "what changed?" signal without requiring a curated
+ * CHANGELOG.
+ *
+ * Pure helpers for building / parsing live here. The actual `release.json`
+ * write happens inside `buildModule` after the staged copy is set up.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export interface ReleaseMetadata {
+  /** Module ID (matches manifest.id) */
+  module_id: string;
+  /** Module version including revision suffix (e.g. "1.2.0+3") */
+  version: string;
+  /** Git commit SHA of the source tree at build time, or null if not in a git checkout */
+  git_sha: string | null;
+  /** Git branch name, or null */
+  git_branch: string | null;
+  /** True if the working tree had uncommitted changes when this was built */
+  git_dirty: boolean;
+  /** ISO-8601 UTC timestamp */
+  published_at: string;
+  /** Version of @celilo/cli that produced the build */
+  published_by_cli_version: string;
+  /** Optional one-line release note from --message */
+  message: string | null;
+}
+
+/**
+ * Pure constructor — takes pre-collected git state and assembles the
+ * structured metadata. The `gitInfo` and `cliVersion` come from the
+ * caller; this keeps the function trivially testable.
+ */
+export function buildReleaseMetadata(opts: {
+  moduleId: string;
+  version: string;
+  git: GitInfo;
+  cliVersion: string;
+  message: string | null;
+  publishedAt?: Date;
+}): ReleaseMetadata {
+  return {
+    module_id: opts.moduleId,
+    version: opts.version,
+    git_sha: opts.git.sha,
+    git_branch: opts.git.branch,
+    git_dirty: opts.git.dirty,
+    published_at: (opts.publishedAt ?? new Date()).toISOString(),
+    published_by_cli_version: opts.cliVersion,
+    message: opts.message,
+  };
+}
+
+export interface GitInfo {
+  sha: string | null;
+  branch: string | null;
+  dirty: boolean;
+}
+
+/**
+ * Resolve the running CLI version by reading the bundled package.json.
+ * Returns "0.0.0" if the file isn't found (dev-from-source without a
+ * package.json shouldn't ever happen in practice, but we shouldn't
+ * crash a publish on it).
+ */
+export function readInstalledCliVersion(): string {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    join(here, '..', '..', '..', 'package.json'),
+    join(process.cwd(), 'package.json'),
+  ];
+  for (const path of candidates) {
+    if (existsSync(path)) {
+      try {
+        const pkg = JSON.parse(readFileSync(path, 'utf-8')) as { version?: string };
+        if (pkg.version) return pkg.version;
+      } catch {
+        // try the next candidate
+      }
+    }
+  }
+  return '0.0.0';
+}
+
+export type GitCommandRunner = (args: string[], cwd: string) => string | null;
+
+/**
+ * Default runner: invoke the system `git` binary, return stdout, or
+ * null on any failure (not a git repo, git not installed, etc.).
+ */
+export function makeRealGitRunner(): GitCommandRunner {
+  // Defer the import so test environments without bun:child_process aren't
+  // affected, and so this file stays pure for the unit tests.
+  const { execFileSync } = require('node:child_process') as typeof import('node:child_process');
+  return (args, cwd) => {
+    try {
+      return execFileSync('git', args, {
+        cwd,
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+      })
+        .toString()
+        .trim();
+    } catch {
+      return null;
+    }
+  };
+}
+
+/**
+ * Collect git SHA, branch, and dirty state from the working tree at
+ * `sourceDir`. Returns nulls / false if the directory isn't in a git
+ * checkout (or git isn't available).
+ */
+export function collectGitInfo(sourceDir: string, run: GitCommandRunner): GitInfo {
+  const sha = run(['rev-parse', 'HEAD'], sourceDir);
+  if (!sha) return { sha: null, branch: null, dirty: false };
+
+  const branch = run(['rev-parse', '--abbrev-ref', 'HEAD'], sourceDir);
+  // `git status --porcelain` prints one line per modified/untracked file.
+  // Empty output = clean. Null (command failure) is treated as not-dirty
+  // because we don't want to falsely block a publish.
+  const status = run(['status', '--porcelain'], sourceDir);
+  const dirty = status !== null && status.length > 0;
+
+  return {
+    sha,
+    branch: branch === 'HEAD' ? null : branch, // detached HEAD reports "HEAD"
+    dirty,
+  };
+}
+
+/**
+ * Filename for the metadata file at the root of every .netapp.
+ */
+export const RELEASE_METADATA_FILENAME = 'release.json';

package/src/registry/client.test.ts

@@ -0,0 +1,228 @@
+import { afterEach, beforeEach, describe, expect, spyOn, test } from 'bun:test';
+import type { IndexEntry } from './client';
+import { DEFAULT_REGISTRY, RegistryClient } from './client';
+
+// ── sparseIndexPath ───────────────────────────────────────────────────────────
+
+describe('RegistryClient.sparseIndexPath', () => {
+  const client = new RegistryClient('https://reg.example.com');
+
+  test('1-char name → index/1/{name}', () => {
+    expect(client.sparseIndexPath('a')).toBe('https://reg.example.com/index/1/a');
+  });
+
+  test('2-char name → index/2/{name}', () => {
+    expect(client.sparseIndexPath('ab')).toBe('https://reg.example.com/index/2/ab');
+  });
+
+  test('3-char name → index/3/{first2}/{name}', () => {
+    expect(client.sparseIndexPath('abc')).toBe('https://reg.example.com/index/3/ab/abc');
+  });
+
+  test('4-char name → index/{01}/{23}/{name}', () => {
+    expect(client.sparseIndexPath('abcd')).toBe('https://reg.example.com/index/ab/cd/abcd');
+  });
+
+  test('long name → index/{01}/{23}/{name}', () => {
+    expect(client.sparseIndexPath('homebridge')).toBe(
+      'https://reg.example.com/index/ho/me/homebridge',
+    );
+  });
+
+  test('real module names produce expected paths', () => {
+    expect(client.sparseIndexPath('caddy')).toBe('https://reg.example.com/index/ca/dd/caddy');
+    expect(client.sparseIndexPath('dns-external')).toBe(
+      'https://reg.example.com/index/dn/s-/dns-external',
+    );
+    expect(client.sparseIndexPath('celilo-registry')).toBe(
+      'https://reg.example.com/index/ce/li/celilo-registry',
+    );
+  });
+});
+
+// ── constructor / baseUrl ─────────────────────────────────────────────────────
+
+describe('RegistryClient constructor', () => {
+  const origEnv = process.env.CELILO_REGISTRY_URL;
+
+  afterEach(() => {
+    if (origEnv === undefined) {
+      process.env.CELILO_REGISTRY_URL = undefined;
+    } else {
+      process.env.CELILO_REGISTRY_URL = origEnv;
+    }
+  });
+
+  test('uses DEFAULT_REGISTRY when no arg and no env var', () => {
+    process.env.CELILO_REGISTRY_URL = undefined;
+    const client = new RegistryClient();
+    expect(client.baseUrl).toBe(DEFAULT_REGISTRY);
+  });
+
+  test('prefers explicit arg over env var', () => {
+    process.env.CELILO_REGISTRY_URL = 'https://env.example.com';
+    const client = new RegistryClient('https://arg.example.com');
+    expect(client.baseUrl).toBe('https://arg.example.com');
+  });
+
+  test('falls back to env var when no arg', () => {
+    process.env.CELILO_REGISTRY_URL = 'https://env.example.com';
+    const client = new RegistryClient();
+    expect(client.baseUrl).toBe('https://env.example.com');
+  });
+
+  test('strips trailing slashes', () => {
+    const client = new RegistryClient('https://reg.example.com///');
+    expect(client.baseUrl).toBe('https://reg.example.com');
+  });
+});
+
+// ── latestVersion ─────────────────────────────────────────────────────────────
+
+describe('RegistryClient.latestVersion', () => {
+  const client = new RegistryClient('https://reg.example.com');
+
+  function entry(vers: string, yanked = false): IndexEntry {
+    return { name: 'test', vers, deps: [], cksum: '', yanked };
+  }
+
+  test('returns undefined for empty entries', () => {
+    expect(client.latestVersion([])).toBeUndefined();
+  });
+
+  test('returns the last non-yanked entry', () => {
+    const entries = [entry('1.0.0+1'), entry('1.0.0+2'), entry('1.0.0+3')];
+    expect(client.latestVersion(entries)?.vers).toBe('1.0.0+3');
+  });
+
+  test('skips yanked versions at the end', () => {
+    const entries = [entry('1.0.0+1'), entry('1.0.0+2'), entry('1.0.0+3', true)];
+    expect(client.latestVersion(entries)?.vers).toBe('1.0.0+2');
+  });
+
+  test('returns undefined when all yanked', () => {
+    const entries = [entry('1.0.0+1', true), entry('1.0.0+2', true)];
+    expect(client.latestVersion(entries)).toBeUndefined();
+  });
+
+  test('does not mutate the original array', () => {
+    const entries = [entry('1.0.0+1'), entry('1.0.0+2')];
+    client.latestVersion(entries);
+    expect(entries[0].vers).toBe('1.0.0+1');
+    expect(entries[1].vers).toBe('1.0.0+2');
+  });
+});
+
+// ── getIndex ──────────────────────────────────────────────────────────────────
+
+describe('RegistryClient.getIndex', () => {
+  let fetchSpy: ReturnType<typeof spyOn>;
+
+  beforeEach(() => {
+    fetchSpy = spyOn(globalThis, 'fetch');
+  });
+
+  afterEach(() => {
+    fetchSpy.mockRestore();
+  });
+
+  function makeNdJson(entries: IndexEntry[]): string {
+    return `${entries.map((e) => JSON.stringify(e)).join('\n')}\n`;
+  }
+
+  test('returns empty array on 404', async () => {
+    fetchSpy.mockResolvedValue(new Response(null, { status: 404 }));
+    const client = new RegistryClient('https://reg.example.com');
+    const result = await client.getIndex('homebridge');
+    expect(result).toEqual([]);
+  });
+
+  test('throws on non-404 error status', async () => {
+    fetchSpy.mockResolvedValue(new Response(null, { status: 500 }));
+    const client = new RegistryClient('https://reg.example.com');
+    await expect(client.getIndex('homebridge')).rejects.toThrow('Registry index error: HTTP 500');
+  });
+
+  test('parses NDJSON index correctly', async () => {
+    const entries: IndexEntry[] = [
+      { name: 'homebridge', vers: '1.4.2+1', deps: [], cksum: 'abc', yanked: false },
+      { name: 'homebridge', vers: '1.4.2+2', deps: [], cksum: 'def', yanked: false },
+    ];
+    fetchSpy.mockResolvedValue(new Response(makeNdJson(entries), { status: 200 }));
+    const client = new RegistryClient('https://reg.example.com');
+    const result = await client.getIndex('homebridge');
+    expect(result).toHaveLength(2);
+    expect(result[0].vers).toBe('1.4.2+1');
+    expect(result[1].vers).toBe('1.4.2+2');
+  });
+
+  test('calls the correct sparse index URL', async () => {
+    fetchSpy.mockResolvedValue(new Response('', { status: 200 }));
+    const client = new RegistryClient('https://reg.example.com');
+    await client.getIndex('homebridge');
+    expect(fetchSpy).toHaveBeenCalledWith(
+      'https://reg.example.com/index/ho/me/homebridge',
+      expect.anything(),
+    );
+  });
+});
+
+// ── publish binary protocol ───────────────────────────────────────────────────
+
+describe('RegistryClient.publish — Cargo binary protocol', () => {
+  let fetchSpy: ReturnType<typeof spyOn>;
+  let tmpFile: string;
+
+  beforeEach(async () => {
+    fetchSpy = spyOn(globalThis, 'fetch');
+    tmpFile = `/tmp/test-publish-${Date.now()}.netapp`;
+    await Bun.write(tmpFile, 'fake netapp content');
+  });
+
+  afterEach(async () => {
+    fetchSpy.mockRestore();
+    if (await Bun.file(tmpFile).exists()) await Bun.write(tmpFile, '');
+  });
+
+  test('constructs correct Cargo binary framing', async () => {
+    fetchSpy.mockResolvedValue(
+      new Response(JSON.stringify({ ok: true, name: 'my-mod', vers: '1.0.0+1' }), { status: 200 }),
+    );
+
+    const client = new RegistryClient('https://reg.example.com');
+    await client.publish({ name: 'my-mod', version: '1.0.0+1', netappPath: tmpFile, token: 'tok' });
+
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchSpy.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe('https://reg.example.com/api/v1/modules/new');
+    expect((init.headers as Record<string, string>).Authorization).toBe('tok');
+
+    const body = init.body as Buffer;
+    const metaLen = body.readUInt32LE(0);
+    const metaJson = JSON.parse(body.subarray(4, 4 + metaLen).toString('utf-8')) as {
+      name: string;
+      vers: string;
+      deps: unknown[];
+      cksum: string;
+    };
+    expect(metaJson.name).toBe('my-mod');
+    expect(metaJson.vers).toBe('1.0.0+1');
+    expect(metaJson.deps).toEqual([]);
+    expect(metaJson.cksum).toMatch(/^sha256:[0-9a-f]{64}$/);
+
+    const fileLen = body.readUInt32LE(4 + metaLen);
+    const fileBytes = body.subarray(4 + metaLen + 4);
+    expect(fileLen).toBe(fileBytes.length);
+    expect(fileBytes.toString('utf-8')).toBe('fake netapp content');
+  });
+
+  test('throws with registry error detail on non-200', async () => {
+    fetchSpy.mockResolvedValue(
+      new Response(JSON.stringify({ errors: [{ detail: 'token invalid' }] }), { status: 403 }),
+    );
+    const client = new RegistryClient('https://reg.example.com');
+    await expect(
+      client.publish({ name: 'mod', version: '1.0.0+1', netappPath: tmpFile, token: 'bad' }),
+    ).rejects.toThrow('token invalid');
+  });
+});

package/src/registry/client.ts

@@ -0,0 +1,157 @@
+/**
+ * Celilo Registry Client
+ *
+ * Implements the Cargo sparse registry protocol for fetching and publishing
+ * modules. Default registry is celilo.computer; can be overridden via
+ * CELILO_REGISTRY_URL or the --registry flag.
+ */
+
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+
+export const DEFAULT_REGISTRY = 'https://celilo.computer/registry';
+
+export interface SparseConfig {
+  dl: string;
+  api: string;
+}
+
+export interface IndexEntry {
+  name: string;
+  vers: string;
+  deps: string[];
+  cksum: string;
+  yanked: boolean;
+}
+
+export interface SearchResult {
+  name: string;
+  max_version: string;
+  description: string;
+}
+
+export interface SearchResponse {
+  modules: SearchResult[];
+  total: number;
+}
+
+export interface ModuleMetadata {
+  name: string;
+  versions: Array<{ num: string; yanked: boolean; created_at: string }>;
+}
+
+export class RegistryClient {
+  readonly baseUrl: string;
+
+  constructor(registryUrl?: string) {
+    // Strip trailing slash for consistent path joining
+    const raw = registryUrl ?? process.env.CELILO_REGISTRY_URL ?? DEFAULT_REGISTRY;
+    this.baseUrl = raw.replace(/\/+$/, '');
+  }
+
+  // ── Sparse index ──────────────────────────────────────────────────────────
+
+  async config(): Promise<SparseConfig> {
+    const resp = await this.get(`${this.baseUrl}/index/config.json`);
+    return resp.json() as Promise<SparseConfig>;
+  }
+
+  sparseIndexPath(name: string): string {
+    if (name.length === 1) return `${this.baseUrl}/index/1/${name}`;
+    if (name.length === 2) return `${this.baseUrl}/index/2/${name}`;
+    if (name.length === 3) return `${this.baseUrl}/index/3/${name.slice(0, 2)}/${name}`;
+    return `${this.baseUrl}/index/${name.slice(0, 2)}/${name.slice(2, 4)}/${name}`;
+  }
+
+  async getIndex(name: string): Promise<IndexEntry[]> {
+    const resp = await fetch(this.sparseIndexPath(name), {
+      signal: AbortSignal.timeout(15_000),
+    });
+    if (resp.status === 404) return [];
+    if (!resp.ok) throw new Error(`Registry index error: HTTP ${resp.status}`);
+    const text = await resp.text();
+    return text
+      .split('\n')
+      .filter(Boolean)
+      .map((line) => JSON.parse(line) as IndexEntry);
+  }
+
+  /** Returns the latest non-yanked version, or undefined if none. */
+  latestVersion(entries: IndexEntry[]): IndexEntry | undefined {
+    return [...entries].reverse().find((e) => !e.yanked);
+  }
+
+  // ── API ───────────────────────────────────────────────────────────────────
+
+  async search(query: string, perPage = 25): Promise<SearchResponse> {
+    const params = new URLSearchParams({ per_page: String(perPage) });
+    if (query) params.set('q', query);
+    const resp = await this.get(`${this.baseUrl}/api/v1/modules?${params}`);
+    return resp.json() as Promise<SearchResponse>;
+  }
+
+  async getModule(name: string): Promise<ModuleMetadata> {
+    const resp = await this.get(`${this.baseUrl}/api/v1/modules/${encodeURIComponent(name)}`);
+    return resp.json() as Promise<ModuleMetadata>;
+  }
+
+  downloadUrl(name: string, version: string): string {
+    return `${this.baseUrl}/api/v1/modules/${encodeURIComponent(name)}/${encodeURIComponent(version)}/download`;
+  }
+
+  async download(name: string, version: string): Promise<ArrayBuffer> {
+    const resp = await this.get(this.downloadUrl(name, version));
+    return resp.arrayBuffer();
+  }
+
+  /**
+   * Publish a module to the registry.
+   *
+   * Follows the Cargo binary protocol:
+   *   [4-byte LE uint32: JSON length] [JSON metadata] [4-byte LE uint32: file length] [.netapp bytes]
+   */
+  async publish(opts: {
+    name: string;
+    version: string;
+    netappPath: string;
+    token: string;
+  }): Promise<{ ok: boolean; name: string; vers: string }> {
+    const fileData = await readFile(opts.netappPath);
+    const cksum = `sha256:${createHash('sha256').update(fileData).digest('hex')}`;
+
+    const meta = JSON.stringify({ name: opts.name, vers: opts.version, deps: [], cksum });
+    const metaBuf = Buffer.from(meta, 'utf-8');
+
+    const body = Buffer.allocUnsafe(4 + metaBuf.length + 4 + fileData.length);
+    body.writeUInt32LE(metaBuf.length, 0);
+    metaBuf.copy(body, 4);
+    body.writeUInt32LE(fileData.length, 4 + metaBuf.length);
+    fileData.copy(body, 4 + metaBuf.length + 4);
+
+    const resp = await fetch(`${this.baseUrl}/api/v1/modules/new`, {
+      method: 'PUT',
+      headers: { Authorization: opts.token, 'Content-Type': 'application/octet-stream' },
+      body,
+      signal: AbortSignal.timeout(120_000),
+    });
+
+    if (!resp.ok) {
+      const err = (await resp.json().catch(() => ({ errors: [{ detail: resp.statusText }] }))) as {
+        errors: Array<{ detail: string }>;
+      };
+      throw new Error(err.errors?.[0]?.detail ?? `HTTP ${resp.status}`);
+    }
+
+    return resp.json() as Promise<{ ok: boolean; name: string; vers: string }>;
+  }
+
+  // ── Internal ──────────────────────────────────────────────────────────────
+
+  private async get(url: string): Promise<Response> {
+    const resp = await fetch(url, { signal: AbortSignal.timeout(15_000) });
+    if (!resp.ok) {
+      throw new Error(`Registry error at ${url}: HTTP ${resp.status}`);
+    }
+    return resp;
+  }
+}