@celilo/cli 1.11.0 → 1.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "description": "Celilo — home lab orchestration CLI",
   "type": "module",
   "bin": {

package/src/cli/commands/module-publish.ts

@@ -61,6 +61,7 @@ interface ManifestForPublish extends ManifestForCapabilityCheck {
   id: string;
   version: string;
   description?: string;
+  icon?: string;
   version_source?: { kind?: string };
 }
 
@@ -307,6 +308,7 @@ export async function publishOneModule(
       netappPath: buildResult.packagePath,
       token: opts.token,
       description: manifest.description?.trim() || undefined,
+      icon: manifest.icon?.trim() || undefined,
     });
   } catch (err) {
     return {

package/src/manifest/icon-schema.test.ts

@@ -0,0 +1,48 @@
+/**
+ * The `icon` field's refinement (openspec/changes/module-icons, D3).
+ *
+ * This is the trust boundary: `manifest.yml` is hand-edited and the value ends
+ * up drawn in a coloured row, so the check that it is monochrome-capable lives
+ * here rather than in any consumer.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { ModuleManifestSchema } from './schema';
+
+function manifestWith(icon?: string): Record<string, unknown> {
+  return {
+    celilo_contract: '1.0',
+    id: 'icon-fixture',
+    name: 'Icon Fixture',
+    version: '1.0.0',
+    ...(icon === undefined ? {} : { icon }),
+  };
+}
+
+describe('manifest icon', () => {
+  test('accepts a BMP non-emoji scalar', () => {
+    const parsed = ModuleManifestSchema.parse(manifestWith('⛨'));
+    expect(parsed.icon).toBe('⛨');
+  });
+
+  test('accepts absence', () => {
+    const parsed = ModuleManifestSchema.parse(manifestWith());
+    expect(parsed.icon).toBeUndefined();
+  });
+
+  test('rejects U+1F512, naming the monochrome reason rather than the range', () => {
+    const result = ModuleManifestSchema.safeParse(manifestWith('🔒'));
+    expect(result.success).toBe(false);
+    if (result.success) throw new Error('expected the padlock to be rejected');
+    const message = result.error.issues[0]?.message ?? '';
+    expect(message).toContain('monochrome');
+    expect(message).toContain('U+1F512');
+  });
+
+  test('rejects a two-character string', () => {
+    const result = ModuleManifestSchema.safeParse(manifestWith('⛨⛨'));
+    expect(result.success).toBe(false);
+    if (result.success) throw new Error('expected two characters to be rejected');
+    expect(result.error.issues[0]?.message ?? '').toContain('exactly one character');
+  });
+});

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

package/src/registry/client.ts

@@ -28,6 +28,8 @@ export interface SearchResult {
   name: string;
   max_version: string;
   description: string;
+  /** The module's declared glyph, absent when it declared none. */
+  icon?: string;
 }
 
 export interface SearchResponse {
@@ -130,6 +132,12 @@ export class RegistryClient {
      * apps/celilo/designs/REGISTRY_BROWSE_UI.md (Phase 2 step 0).
      */
     description?: string;
+    /**
+     * The module's `manifest.yml#icon`, when it declares one. Optional and
+     * server-tolerated in its absence, exactly like `description`
+     * (openspec/changes/module-icons, D4).
+     */
+    icon?: string;
   }): Promise<{ ok: boolean; name: string; vers: string }> {
     const fileData = await readFile(opts.netappPath);
     const cksum = `sha256:${createHash('sha256').update(fileData).digest('hex')}`;
@@ -140,6 +148,7 @@ export class RegistryClient {
       deps: [],
       cksum,
       ...(opts.description ? { description: opts.description } : {}),
+      ...(opts.icon ? { icon: opts.icon } : {}),
     });
     const metaBuf = Buffer.from(meta, 'utf-8');