@celilo/cli 1.11.0 → 1.13.0

package/src/manifest/schema.ts

@@ -563,6 +563,14 @@ export type ModuleSubscription = z.infer<typeof ModuleSubscriptionSchema>;
  * with via `celilo_contract`. The contract version determines the
  * canonical inputs/outputs of every lifecycle hook (see `./contracts/v1.ts`).
  */
+/**
+ * Codepoints carrying Unicode's `Emoji` property, which the `icon` field
+ * rejects. Note this property is broader than "looks like an emoji": ASCII
+ * digits, `#` and `*` carry it too, because they form keycap sequences. That
+ * over-rejection costs nothing — none of them is a plausible module glyph.
+ */
+const EMOJI_CODEPOINT = /\p{Emoji}/u;
+
 export const ModuleManifestSchema = z
   .object({
     /**
@@ -584,6 +592,55 @@ export const ModuleManifestSchema = z
     version: z.string().regex(/^\d+\.\d+\.\d+$/, 'Version must be semantic version (e.g., 1.0.0)'),
     description: z.string().optional(),
 
+    /**
+     * One glyph identifying this module wherever celilo draws it — the console
+     * roster, the topology boxes, the registry browse page. Optional: a module
+     * declaring none falls back to the consumer's built-in table, then to a
+     * placeholder (openspec/changes/module-icons, D3/D5).
+     *
+     * Exactly one Unicode scalar, inside the BMP, without Unicode's `Emoji`
+     * property. These glyphs inherit the colour of the row they are drawn in,
+     * so a firing module's icon goes red with the rest of the row. An emoji
+     * codepoint paints its own colours and would stay cheerful while its
+     * module's state said otherwise.
+     *
+     * BMP-and-not-Emoji is a PROXY for "renders monochrome", not a proof. Some
+     * BMP codepoints outside the Emoji property still get an emoji font on some
+     * platforms. What it does catch is the whole SMP emoji range, which is
+     * where an author reaching for a padlock or a shield actually lands, and
+     * that is the case worth catching.
+     *
+     * `ModuleManifestSchema` is strict, so a celilo predating this field
+     * rejects a manifest declaring it. The CLI release accepting `icon` ships
+     * before any module published to the registry declares one (D2).
+     */
+    icon: z
+      .string()
+      .superRefine((value, ctx) => {
+        const scalars = [...value];
+        if (scalars.length !== 1) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `icon must be exactly one character, got ${scalars.length}`,
+          });
+          return;
+        }
+        const codePoint = value.codePointAt(0) ?? 0;
+        if (codePoint > 0xffff || EMOJI_CODEPOINT.test(value)) {
+          const hex = codePoint.toString(16).toUpperCase().padStart(4, '0');
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: [
+              `icon '${value}' (U+${hex}) must be a monochrome glyph: it inherits the colour`,
+              'of the row it is drawn in, and an emoji codepoint paints its own colours, so it',
+              "would stay cheerful while the module went red. Use a BMP symbol outside Unicode's",
+              "Emoji property (a key '\u26bf', not a padlock '\u{1f512}').",
+            ].join(' '),
+          });
+        }
+      })
+      .optional(),
+
     /**
      * How `manifest.yml#version` (the PAYLOAD version) is determined — see
      * openspec/changes/module-version-semantics/proposal.md / ISS-0151. The capability *contract* version
@@ -608,6 +665,41 @@ export const ModuleManifestSchema = z
       .strict()
       .optional(),
 
+    /**
+     * Submodules this module owns (openspec/changes/submodules, D1).
+     *
+     * Each name is a directory under this module's own `submodules/`, holding
+     * an ordinary module manifest. A submodule is never a top-level module: an
+     * operator does not import it, does not deploy it, and never sees it in the
+     * registry. It ships inside this package, versions with this manifest, and
+     * exists only as instances this module creates through the
+     * `celilo_module_deploy_worker` capability.
+     *
+     * Ownership is declared by the PARENT rather than flagged on the child, and
+     * that is what makes the exclusivity structural rather than enforced. A
+     * submodule is not in `modules/`, so there is nothing to deploy by accident
+     * and no flag for a code path to forget to check.
+     *
+     * A plain list of names, not a block. Per-submodule policy such as a
+     * maximum instance count is the operator's business rather than the
+     * author's — the same reason `requires.system` states a minimum rather than
+     * a deployed size. A `string | object` union stays reachable additively if
+     * a genuinely author-owned per-submodule fact ever turns up.
+     *
+     * v1.0 contract field — additive, no contract version bump needed, exactly
+     * like `optional.capabilities`.
+     */
+    submodules: z
+      .array(
+        z
+          .string()
+          .regex(
+            /^[a-z0-9]+(-[a-z0-9]+)*$/,
+            'Submodule name must use kebab-case — it names a directory under submodules/',
+          ),
+      )
+      .optional(),
+
     requires: z
       .object({
         capabilities: z.array(CapabilityRequirementSchema).default([]),

package/src/manifest/validate.test.ts

@@ -7,6 +7,8 @@ import {
   validateHookContract,
   validateManifest,
   validateProvidesNoCrossCapabilityRefs,
+  validateSubmoduleDeclaration,
+  validateSubmoduleManifest,
   validateVariableSources,
 } from './validate';
 
@@ -1531,3 +1533,143 @@ base_module_aspect:
     expect(result.success).toBe(false);
   });
 });
+
+describe('submodules (openspec/changes/submodules D1, D9)', () => {
+  const parent = (over: Record<string, unknown> = {}) => ({
+    celilo_contract: '1.0' as const,
+    id: 'forgejo',
+    name: 'Forgejo',
+    version: '1.0.0',
+    requires: { capabilities: [] },
+    provides: { capabilities: [] },
+    variables: { owns: [], imports: [] },
+    ...over,
+  });
+
+  const submodule = (over: Record<string, unknown> = {}) => ({
+    celilo_contract: '1.0' as const,
+    id: 'runner',
+    name: 'Forgejo Runner',
+    version: '1.0.0',
+    requires: { capabilities: [] },
+    provides: { capabilities: [] },
+    variables: { owns: [], imports: [] },
+    ...over,
+  });
+
+  describe('validateSubmoduleDeclaration', () => {
+    test('a module declaring no submodules is unaffected', () => {
+      expect(validateSubmoduleDeclaration(parent())).toBeNull();
+    });
+
+    test('accepts a plain list of names', () => {
+      expect(validateSubmoduleDeclaration(parent({ submodules: ['runner'] }))).toBeNull();
+    });
+
+    test('rejects a duplicate name', () => {
+      const result = validateSubmoduleDeclaration(parent({ submodules: ['runner', 'runner'] }));
+      expect(result).not.toBeNull();
+      expect(result?.errors[0]?.message).toContain('more than once');
+    });
+
+    test('rejects a submodule sharing its parent id', () => {
+      const result = validateSubmoduleDeclaration(parent({ submodules: ['forgejo'] }));
+      expect(result).not.toBeNull();
+      expect(result?.errors[0]?.message).toContain("parent module's id");
+    });
+  });
+
+  describe('validateSubmoduleManifest', () => {
+    test('accepts an ordinary submodule manifest', () => {
+      expect(validateSubmoduleManifest(parent(), 'runner', submodule())).toBeNull();
+    });
+
+    test('rejects an id that disagrees with its directory', () => {
+      const result = validateSubmoduleManifest(parent(), 'runner', submodule({ id: 'builder' }));
+      expect(result).not.toBeNull();
+      expect(result?.errors[0]?.message).toContain('does not match its directory');
+    });
+
+    // D9: a capability resolves to ONE provider, and celilo's two bespoke
+    // multi-provider rules RESOLVE rather than fail, so N instances would bind
+    // a consumer to whichever was created first — silently.
+    test('rejects a submodule that provides a capability', () => {
+      const result = validateSubmoduleManifest(
+        parent(),
+        'runner',
+        submodule({
+          provides: { capabilities: [{ name: 'source_forge', version: '1.0.0', data: {} }] },
+        }),
+      );
+      expect(result).not.toBeNull();
+      expect(result?.errors[0]?.message).toContain('may not provide a capability');
+      expect(result?.errors[0]?.message).toContain('source_forge');
+    });
+
+    test('a submodule may still REQUIRE capabilities', () => {
+      const result = validateSubmoduleManifest(
+        parent(),
+        'runner',
+        submodule({ requires: { capabilities: [{ name: 'source_forge', version: '1.0.0' }] } }),
+      );
+      expect(result).toBeNull();
+    });
+
+    test('rejects nesting — ownership is one level deep', () => {
+      const result = validateSubmoduleManifest(
+        parent(),
+        'runner',
+        submodule({ submodules: ['nested'] }),
+      );
+      expect(result).not.toBeNull();
+      expect(result?.errors[0]?.message).toContain('may not declare submodules of its own');
+    });
+
+    test('reports every problem at once rather than stopping at the first', () => {
+      const result = validateSubmoduleManifest(
+        parent(),
+        'runner',
+        submodule({
+          id: 'builder',
+          provides: { capabilities: [{ name: 'source_forge', version: '1.0.0', data: {} }] },
+          submodules: ['nested'],
+        }),
+      );
+      expect(result?.errors).toHaveLength(3);
+    });
+  });
+
+  describe('schema', () => {
+    test('parses a manifest declaring submodules', () => {
+      const yaml = `
+celilo_contract: "1.0"
+id: forgejo
+name: Forgejo
+version: 1.0.0
+submodules:
+  - runner
+requires:
+  capabilities: []
+`;
+      const result = validateManifest(yaml);
+      expect(result.success).toBe(true);
+      if (result.success) expect(result.data.submodules).toEqual(['runner']);
+    });
+
+    test('rejects a non-kebab-case submodule name', () => {
+      const yaml = `
+celilo_contract: "1.0"
+id: forgejo
+name: Forgejo
+version: 1.0.0
+submodules:
+  - Runner_One
+requires:
+  capabilities: []
+`;
+      const result = validateManifest(yaml);
+      expect(result.success).toBe(false);
+      if (!result.success) expect(result.errors[0]?.message).toContain('kebab-case');
+    });
+  });
+});

package/src/manifest/validate.ts

@@ -1,6 +1,7 @@
 import { KNOWN_CAPABILITY_NAMES, isProviderView } from '@celilo/capabilities';
 import { parse as parseYaml } from 'yaml';
 import type { ZodError } from 'zod';
+import { SUBMODULES_DIR } from '../module/packaging/package-rules';
 import { validateModuleZoneRequirements } from '../services/zone-policy';
 import { resolveContract, supportedContractVersions } from './contracts';
 import { ModuleManifestSchema, getSingularSystemSpec } from './schema';
@@ -495,3 +496,103 @@ export function validateProvidesNoCrossCapabilityRefs(
 
   return null;
 }
+
+/**
+ * The directory a parent's submodules live in, relative to the parent's own
+ * source root. Re-exported rather than redefined: the packaging rules need the
+ * same name and `package-rules.ts` is deliberately dependency-free (the
+ * registry server imports it), so it owns the definition and everything
+ * manifest-facing reads it from here.
+ */
+export { SUBMODULES_DIR };
+
+/**
+ * Validate a PARENT's `submodules` declaration.
+ *
+ * Policy function - checks the declaration itself, not the submodules it names.
+ * Reading those is I/O and belongs to the caller.
+ *
+ * @param manifest - Validated manifest of the parent
+ * @returns Validation errors if any, null if clean
+ */
+export function validateSubmoduleDeclaration(manifest: ModuleManifest): ValidationError | null {
+  const declared = manifest.submodules ?? [];
+  if (declared.length === 0) return null;
+
+  const errors: Array<{ path: string; message: string }> = [];
+  const seen = new Set<string>();
+
+  for (const [index, name] of declared.entries()) {
+    if (seen.has(name)) {
+      errors.push({
+        path: `submodules.${index}`,
+        message: `Submodule '${name}' is declared more than once`,
+      });
+    }
+    seen.add(name);
+
+    // The derived id of an instance is built from the parent and the submodule
+    // name, so a submodule sharing its parent's id yields an instance id that
+    // reads as the parent's own. Cheap to refuse, confusing to debug.
+    if (name === manifest.id) {
+      errors.push({
+        path: `submodules.${index}`,
+        message: `Submodule '${name}' cannot share its parent module's id`,
+      });
+    }
+  }
+
+  return errors.length > 0 ? { success: false, errors } : null;
+}
+
+/**
+ * Validate that a SUBMODULE's own manifest is legal as a submodule.
+ *
+ * Policy function - the caller has already read and schema-validated the
+ * submodule's manifest; this decides whether it may be one.
+ *
+ * @param parent - The declaring parent's manifest
+ * @param submoduleName - The name the parent declared, i.e. its directory
+ * @param submodule - The submodule's own validated manifest
+ * @returns Validation errors if any, null if clean
+ */
+export function validateSubmoduleManifest(
+  parent: ModuleManifest,
+  submoduleName: string,
+  submodule: ModuleManifest,
+): ValidationError | null {
+  const errors: Array<{ path: string; message: string }> = [];
+  const where = `${SUBMODULES_DIR}/${submoduleName}/manifest.yml`;
+
+  if (submodule.id !== submoduleName) {
+    errors.push({
+      path: `${where}#id`,
+      message: `Submodule id '${submodule.id}' does not match its directory '${submoduleName}'. A submodule is addressed by the name its parent declares, so the two must agree.`,
+    });
+  }
+
+  // D9: celilo has no general rule for resolving a capability name to one of
+  // several providers. The two bespoke rules that exist RESOLVE rather than
+  // fail — `firewall` builds a chain, `dns_registrar` takes the first row — so
+  // N instances registering one capability would silently bind a consumer to
+  // whichever was created first. Refused here rather than discovered there.
+  if ((submodule.provides?.capabilities ?? []).length > 0) {
+    const names = submodule.provides.capabilities.map((c) => c.name).join(', ');
+    errors.push({
+      path: `${where}#provides.capabilities`,
+      message: `A submodule may not provide a capability (declares: ${names}). A capability resolves to ONE provider, and a submodule exists as many instances, so a consumer would bind to whichever instance happened to be created first. Move the capability to '${parent.id}'.`,
+    });
+  }
+
+  // One level only. D4's instance layout puts every instance flat under
+  // `modules/`, and nesting would make a derived id ambiguous about which
+  // ancestor owns it.
+  if ((submodule.submodules ?? []).length > 0) {
+    errors.push({
+      path: `${where}#submodules`,
+      message: `A submodule may not declare submodules of its own. Ownership is one level deep: '${parent.id}' owns '${submoduleName}', and nothing owns anything below that.`,
+    });
+  }
+
+  return errors.length > 0 ? { success: false, errors } : null;
+}

package/src/module/import.test.ts

@@ -171,6 +171,122 @@ version: 1.0.0
     });
   });
 
+  describe('submodules (openspec/changes/submodules D1)', () => {
+    const PARENT = `
+celilo_contract: "1.0"
+id: forgejo
+name: Forgejo
+version: 1.0.0
+submodules:
+  - runner
+`;
+    const SUBMODULE = `
+celilo_contract: "1.0"
+id: runner
+name: Forgejo Runner
+version: 1.0.0
+`;
+
+    async function writeParent(dirName: string, parent: string, submodule?: string) {
+      const moduleDir = join(TEST_FIXTURES_DIR, dirName);
+      await mkdir(moduleDir, { recursive: true });
+      await writeFile(join(moduleDir, 'manifest.yml'), parent);
+      if (submodule !== undefined) {
+        const subDir = join(moduleDir, 'submodules', 'runner');
+        await mkdir(subDir, { recursive: true });
+        await writeFile(join(subDir, 'manifest.yml'), submodule);
+      }
+      return moduleDir;
+    }
+
+    test('accepts a parent whose declared submodule is present and legal', async () => {
+      const dir = await writeParent('forgejo-ok', PARENT, SUBMODULE);
+      const result = await readModuleManifest(dir);
+      expect(result.success).toBe(true);
+      if (result.success) expect(result.manifest.submodules).toEqual(['runner']);
+    });
+
+    // The point of validating at PARENT import: an instantiation happens with
+    // no operator present, which is the worst moment to learn a manifest is
+    // broken.
+    test('rejects a parent declaring a submodule that does not exist', async () => {
+      const dir = await writeParent('forgejo-missing', PARENT);
+      const result = await readModuleManifest(dir);
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        expect(result.error).toContain('submodules/runner/manifest.yml does not exist');
+      }
+    });
+
+    test('rejects a parent whose submodule provides a capability', async () => {
+      const dir = await writeParent(
+        'forgejo-provides',
+        PARENT,
+        `${SUBMODULE}
+provides:
+  capabilities:
+    - name: source_forge
+      version: 1.0.0
+      data: {}
+`,
+      );
+      const result = await readModuleManifest(dir);
+      expect(result.success).toBe(false);
+      if (!result.success) expect(result.error).toContain('may not provide a capability');
+    });
+
+    test('rejects a submodule whose id disagrees with its directory', async () => {
+      const dir = await writeParent(
+        'forgejo-mismatch',
+        PARENT,
+        SUBMODULE.replace('id: runner', 'id: builder'),
+      );
+      const result = await readModuleManifest(dir);
+      expect(result.success).toBe(false);
+      if (!result.success) expect(result.error).toContain('does not match its directory');
+    });
+
+    test('a module declaring no submodules is unaffected', async () => {
+      const dir = await writeParent(
+        'plain-module',
+        `
+celilo_contract: "1.0"
+id: plain
+name: Plain
+version: 1.0.0
+`,
+      );
+      const result = await readModuleManifest(dir);
+      expect(result.success).toBe(true);
+    });
+
+    // A submodule reaches the fleet inside its parent's package. The registry
+    // path is already closed (submodules are never published separately), so a
+    // local path is the only open door and this is what shuts it.
+    test('refuses to import a submodule directory on its own, naming the parent', async () => {
+      await writeParent('forgejo-direct', PARENT, SUBMODULE);
+      const submodulePath = join(TEST_FIXTURES_DIR, 'forgejo-direct', 'submodules', 'runner');
+
+      const error = validateModuleDirectory(submodulePath);
+
+      expect(error).not.toBeNull();
+      expect(error).toContain("is a submodule of 'forgejo-direct'");
+      expect(error).toContain('Import');
+    });
+
+    test('a trailing slash does not defeat the submodule refusal', async () => {
+      await writeParent('forgejo-slash', PARENT, SUBMODULE);
+      const submodulePath = `${join(TEST_FIXTURES_DIR, 'forgejo-slash', 'submodules', 'runner')}/`;
+
+      expect(validateModuleDirectory(submodulePath)).toContain('is a submodule of');
+    });
+
+    test('an ordinary module directory is still importable', async () => {
+      const dir = await writeParent('ordinary', PARENT, SUBMODULE);
+      expect(validateModuleDirectory(dir)).toBeNull();
+    });
+  });
+
   describe('copyModuleFiles', () => {
     test('should copy all files from source to target', async () => {
       const sourceDir = join(TEST_FIXTURES_DIR, 'source');

package/src/module/import.ts

@@ -1,7 +1,7 @@
 import { execSync } from 'node:child_process';
 import { existsSync, statSync, writeFileSync } from 'node:fs';
 import { copyFile, mkdir, readFile, readdir } from 'node:fs/promises';
-import { join, relative } from 'node:path';
+import { basename, dirname, join, relative } from 'node:path';
 import { eq } from 'drizzle-orm';
 import { z } from 'zod';
 import { getWellKnownCapability, isWellKnown } from '../capabilities/well-known';
@@ -12,12 +12,15 @@ import { capabilities, moduleIntegrity, modules } from '../db/schema';
 import type { NewModule, NewModuleIntegrity } from '../db/schema';
 import { type ModuleManifest, getSingularSystemSpec } from '../manifest/schema';
 import {
+  SUBMODULES_DIR,
   validateCapabilityNames,
   validateDeriveFromSources,
   validateHookContract,
   validateManifest,
   validatePrivilegedCapabilities,
   validateProvidesNoCrossCapabilityRefs,
+  validateSubmoduleDeclaration,
+  validateSubmoduleManifest,
   validateVariableSources,
   validateZoneRequirements,
 } from '../manifest/validate';
@@ -93,6 +96,17 @@ export function validateModuleDirectory(sourcePath: string): string | null {
     return `Module directory does not exist: ${sourcePath}`;
   }
 
+  // A submodule is not a module (design D1). It reaches the fleet inside its
+  // parent's package and exists only as instances the parent creates, so
+  // importing one on its own would produce a top-level module that was never
+  // written to be singular. The registry path is already closed — submodules
+  // are never published separately — so a local path is the only open door.
+  const parentDir = dirname(sourcePath.replace(/\/+$/, ''));
+  if (basename(parentDir) === SUBMODULES_DIR) {
+    const owner = basename(dirname(parentDir));
+    return `'${basename(sourcePath)}' is a submodule of '${owner}', not a module. Import '${owner}' instead — its package carries this submodule, and only '${owner}' can instantiate it.`;
+  }
+
   // Check it's a directory
   const stats = statSync(sourcePath);
   if (!stats.isDirectory()) {
@@ -208,12 +222,70 @@ export async function readModuleManifest(
     };
   }
 
+  const submoduleCheck = await validateDeclaredSubmodules(sourcePath, validationResult.data);
+  if (submoduleCheck) {
+    return { success: false, error: submoduleCheck };
+  }
+
   return {
     success: true,
     manifest: validationResult.data,
   };
 }
 
+/**
+ * Read and validate every submodule a parent declares.
+ *
+ * Runs at PARENT IMPORT so a broken submodule fails the parent, rather than
+ * surfacing at the first instantiation — which happens with no operator
+ * present and is the worst possible moment to learn a manifest is wrong
+ * (design D1).
+ *
+ * @param sourcePath - The parent's module directory
+ * @param parent - The parent's validated manifest
+ * @returns An error message if any submodule is missing or illegal, null if clean
+ */
+async function validateDeclaredSubmodules(
+  sourcePath: string,
+  parent: ModuleManifest,
+): Promise<string | null> {
+  const declarationCheck = validateSubmoduleDeclaration(parent);
+  if (declarationCheck) {
+    const errorMessages = declarationCheck.errors.map((e) => `${e.path}: ${e.message}`).join('\n');
+    return `Submodule declaration validation failed:\n${errorMessages}`;
+  }
+
+  for (const name of parent.submodules ?? []) {
+    const submodulePath = join(sourcePath, SUBMODULES_DIR, name);
+    const manifestPath = join(submodulePath, 'manifest.yml');
+
+    if (!existsSync(manifestPath)) {
+      return `Module '${parent.id}' declares submodule '${name}', but ${SUBMODULES_DIR}/${name}/manifest.yml does not exist.`;
+    }
+
+    let yamlContent: string;
+    try {
+      yamlContent = await readFile(manifestPath, 'utf-8');
+    } catch (error) {
+      return `Failed to read ${SUBMODULES_DIR}/${name}/manifest.yml: ${error instanceof Error ? error.message : 'Unknown error'}`;
+    }
+
+    const parsed = validateManifest(yamlContent);
+    if (!parsed.success) {
+      const errorMessages = parsed.errors.map((e) => `${e.path}: ${e.message}`).join(', ');
+      return `Submodule '${name}' has an invalid manifest: ${errorMessages}`;
+    }
+
+    const submoduleCheck = validateSubmoduleManifest(parent, name, parsed.data);
+    if (submoduleCheck) {
+      const errorMessages = submoduleCheck.errors.map((e) => `${e.path}: ${e.message}`).join('\n');
+      return `Submodule '${name}' validation failed:\n${errorMessages}`;
+    }
+  }
+
+  return null;
+}
+
 /**
  * Copy module files to target directory
  *