@mycadet/cli 0.0.1 → 0.12.6-dev.202610080043.b727a33

package/node_modules/@mycadet/avatar-manifest/src/manifest.ts

@@ -0,0 +1,208 @@
+import { isAvatarAccentHex } from "./accent.js";
+
+export type AvatarKind = "character" | "image" | "none";
+export type AvatarSource = "builder" | "upload" | "ai";
+
+export interface CharacterTraits {
+  bodyShape: string;
+  eyeStyle: string;
+  color: string;
+}
+
+export interface AvatarImageMeta {
+  updatedAt: string;
+  etag: string;
+}
+
+/**
+ * Where an accent came from. `palette`: a character's chosen colour.
+ * `derived`: read out of an uploaded image's pixels. `custom`: set by the
+ * user over an image. Only the last is worth offering a reset from.
+ */
+export type AvatarAccentSource = "palette" | "derived" | "custom";
+
+/** The colour every avatar-tinted surface paints with, as `#rrggbb`. */
+export interface AvatarAccent {
+  hex: string;
+  source: AvatarAccentSource;
+}
+
+/** The persisted manifest (`avatar.json`). */
+export interface AvatarState {
+  kind: AvatarKind;
+  traits: CharacterTraits | null;
+  source: AvatarSource | null;
+  image: AvatarImageMeta | null;
+  /** Null for `none`, and for an image whose colour could not be read. */
+  accent: AvatarAccent | null;
+}
+
+const AVATAR_KINDS: ReadonlySet<string> = new Set<AvatarKind>([
+  "character",
+  "image",
+  "none",
+]);
+
+const AVATAR_SOURCES: ReadonlySet<string> = new Set<AvatarSource>([
+  "builder",
+  "upload",
+  "ai",
+]);
+
+const AVATAR_ACCENT_SOURCES: ReadonlySet<string> = new Set<AvatarAccentSource>([
+  "palette",
+  "derived",
+  "custom",
+]);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object";
+}
+
+/** Longest string any manifest field may carry (trait ids, etags, timestamps). */
+export const AVATAR_FIELD_MAX_LENGTH = 256;
+
+function isBoundedString(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    value.length > 0 &&
+    value.length <= AVATAR_FIELD_MAX_LENGTH
+  );
+}
+
+/** Narrows an unknown value to valid CharacterTraits (presence and length only). */
+function isValidCharacterTraits(value: unknown): value is CharacterTraits {
+  return (
+    isRecord(value) &&
+    isBoundedString(value.bodyShape) &&
+    isBoundedString(value.eyeStyle) &&
+    isBoundedString(value.color)
+  );
+}
+
+/** Narrows an unknown value to valid AvatarImageMeta (presence and length only). */
+function isValidAvatarImageMeta(value: unknown): value is AvatarImageMeta {
+  return (
+    isRecord(value) &&
+    isBoundedString(value.updatedAt) &&
+    isBoundedString(value.etag)
+  );
+}
+
+/**
+ * An accent is optional on the wire and in the file: manifests written before
+ * accents existed carry none, and an unreadable image has none. Anything not
+ * a well-formed accent normalizes to null rather than failing the manifest.
+ */
+function parseAvatarAccent(value: unknown): AvatarAccent | null {
+  if (
+    !isRecord(value) ||
+    !isAvatarAccentHex(value.hex) ||
+    typeof value.source !== "string" ||
+    !AVATAR_ACCENT_SOURCES.has(value.source)
+  ) {
+    return null;
+  }
+  return { hex: value.hex, source: value.source as AvatarAccentSource };
+}
+
+/**
+ * Validates a parsed `avatar.json`. Returns `null` for a non-object, an
+ * invalid or missing `kind`, or a valid `kind` whose per-kind payload is
+ * missing or malformed, so callers fall back to legacy derivation instead
+ * of surfacing an avatar with null traits/image. An unknown `source` and any
+ * payload irrelevant to the kind normalize to `null` rather than passing
+ * through, so the result always satisfies the wire shape.
+ */
+export function parseAvatarManifest(value: unknown): AvatarState | null {
+  if (!isRecord(value)) {
+    return null;
+  }
+  if (typeof value.kind !== "string" || !AVATAR_KINDS.has(value.kind)) {
+    return null;
+  }
+  const kind = value.kind as AvatarKind;
+  const source =
+    typeof value.source === "string" && AVATAR_SOURCES.has(value.source)
+      ? (value.source as AvatarSource)
+      : null;
+  if (kind === "character") {
+    if (!isValidCharacterTraits(value.traits)) {
+      return null;
+    }
+    return {
+      kind,
+      traits: value.traits,
+      source,
+      image: null,
+      accent: parseAvatarAccent(value.accent),
+    };
+  }
+  if (kind === "image") {
+    if (!isValidAvatarImageMeta(value.image)) {
+      return null;
+    }
+    return {
+      kind,
+      traits: null,
+      source,
+      image: value.image,
+      accent: parseAvatarAccent(value.accent),
+    };
+  }
+  return { kind, traits: null, source, image: null, accent: null };
+}
+
+type LegacyAvatarDerivation =
+  | { kind: "character"; traits: CharacterTraits }
+  | { kind: "image" }
+  | { kind: "none" };
+
+/**
+ * Derives the avatar from the legacy sidecar files when there is no usable
+ * manifest. Traits-first: valid traits win even when the PNG also exists,
+ * because the builder writes the rendered PNG after the traits file, so
+ * mtimes cannot tell a built character from an uploaded image.
+ */
+export function deriveAvatarFromLegacyFiles(input: {
+  traitsJson: unknown;
+  hasImage: boolean;
+}): LegacyAvatarDerivation {
+  if (isValidCharacterTraits(input.traitsJson)) {
+    return { kind: "character", traits: input.traitsJson };
+  }
+  return input.hasImage ? { kind: "image" } : { kind: "none" };
+}
+
+type ResolvedAvatar =
+  | { kind: "character"; traits: CharacterTraits }
+  | { kind: "image"; image: AvatarImageMeta | null }
+  | { kind: "none" };
+
+/**
+ * Resolves the avatar from the parsed avatar files: the manifest when it is
+ * valid, otherwise the legacy derivation. `image` carries the manifest's
+ * metadata when the manifest decided, and is null for a legacy PNG.
+ */
+export function resolveAvatarFromFiles(input: {
+  manifestJson: unknown;
+  traitsJson: unknown;
+  hasImage: boolean;
+}): ResolvedAvatar {
+  const manifest = parseAvatarManifest(input.manifestJson);
+  if (manifest) {
+    switch (manifest.kind) {
+      case "character":
+        return {
+          kind: "character",
+          traits: manifest.traits as CharacterTraits,
+        };
+      case "image":
+        return { kind: "image", image: manifest.image };
+      case "none":
+        return { kind: "none" };
+    }
+  }
+  const legacy = deriveAvatarFromLegacyFiles(input);
+  return legacy.kind === "image" ? { kind: "image", image: null } : legacy;
+}

package/node_modules/@mycadet/avatar-manifest/src/notification-avatar.ts

@@ -0,0 +1,143 @@
+/**
+ * The notification avatar: the assistant's avatar centered on an accent-tinted
+ * disc, the icon a native notification shows as the sender.
+ *
+ * The disc is inscribed in the square, so the four corners stay transparent.
+ * That is deliberate: iOS, Android, and the Windows toast logo slot all
+ * circle-crop what they are handed, and a square of colour behind the disc
+ * would only show through as a ring on any surface that does not crop. The
+ * disc itself is fully opaque, and so is everything inside it.
+ *
+ * Every platform draws the same picture with a different rasterizer (resvg in
+ * the daemon, a canvas in the desktop renderer), so the geometry and the disc
+ * colour live here once. Pure arithmetic and string building, no decoder and
+ * no node builtins, so a browser can call it too.
+ */
+
+import { isAvatarAccentHex } from "./accent.js";
+import type { AvatarKind } from "./manifest.js";
+
+/** Output edge in pixels: large enough for an iOS notification thumbnail. */
+export const NOTIFICATION_AVATAR_SIZE = 256;
+
+/** Free disc on each side of a character avatar, as a fraction of the edge. */
+export const NOTIFICATION_AVATAR_INSET = 0.11;
+
+/** The disc when the assistant has no accent. */
+export const NOTIFICATION_AVATAR_FALLBACK_DISC_HEX = "#ECEFEA";
+
+/** How much of the accent survives the mix into white. */
+const ACCENT_MIX = 0.14;
+
+/**
+ * Largest notification PNG the platform sync ships, in bytes. It bounds the
+ * `notification_avatar_base64` field of the PATCH that uploads the disc, which
+ * is what APNs and FCM later hand their clients a URL and a hash for. A
+ * photographic avatar is quantised (or dropped) to fit.
+ */
+export const NOTIFICATION_AVATAR_MAX_BYTES = 128 * 1024;
+
+/**
+ * Largest notification PNG the local desktop path carries, in bytes. The
+ * renderer composites the disc, hands it to the Electron host over IPC and the
+ * host caches it on disk, so nothing crosses a push transport and a
+ * photographic avatar that renders past the sync cap still shows.
+ */
+export const NOTIFICATION_AVATAR_MAX_LOCAL_BYTES = 512 * 1024;
+
+/**
+ * Bumped whenever the drawing above changes, so a sync keyed on it re-uploads
+ * a disc rendered by an older spec even when the avatar itself is unchanged.
+ */
+export const NOTIFICATION_AVATAR_SPEC_VERSION = 2;
+
+/** The id the inner raster's clip path is referenced by inside the document. */
+const CLIP_ID = "notification-avatar-disc";
+
+/**
+ * The disc fill for an accent: the accent mixed into white, so the avatar reads
+ * against it at notification size. Uppercase `#RRGGBB`; the neutral fallback
+ * when there is no accent or the value is not a hex.
+ */
+export function notificationAvatarDiscHex(accentHex: string | null): string {
+  if (!isAvatarAccentHex(accentHex)) {
+    return NOTIFICATION_AVATAR_FALLBACK_DISC_HEX;
+  }
+  const rgb = parseInt(accentHex.slice(1), 16);
+  const mixed = (shift: number) => {
+    const channel = (rgb >> shift) & 0xff;
+    return Math.round(255 + (channel - 255) * ACCENT_MIX)
+      .toString(16)
+      .padStart(2, "0");
+  };
+  return `#${mixed(16)}${mixed(8)}${mixed(0)}`.toUpperCase();
+}
+
+/** Raster formats an `<image>` href carries here; what resvg and a canvas both decode. */
+export type NotificationAvatarMediaType =
+  "image/png" | "image/jpeg" | "image/gif";
+
+/**
+ * The three measurements the drawing derives from the edge: the disc's radius,
+ * which is also its centre; the free border around the avatar; and the
+ * avatar's own edge. Every rasterizer reads them from here, so the daemon's
+ * SVG and the desktop canvas cannot drift.
+ * Custom images fill the disc; character avatars retain space around their
+ * silhouette.
+ */
+export function notificationAvatarGeometry(
+  kind: Exclude<AvatarKind, "none">,
+  size: number = NOTIFICATION_AVATAR_SIZE,
+): { radius: number; offset: number; inner: number } {
+  const offset = kind === "character" ? size * NOTIFICATION_AVATAR_INSET : 0;
+  return { radius: size / 2, offset, inner: size - 2 * offset };
+}
+
+export interface NotificationAvatarSvgOptions {
+  kind: Exclude<AvatarKind, "none">;
+  /** The avatar raster to draw inside the disc, base64 with no data prefix. */
+  innerPngBase64: string;
+  /** What `innerPngBase64` holds; PNG unless an upload arrived as a JPEG or a GIF. */
+  innerMediaType?: NotificationAvatarMediaType;
+  accentHex: string | null;
+  size?: number;
+}
+
+/** Trims the float noise a fractional inset leaves in the coordinates. */
+function px(value: number): string {
+  return String(Number(value.toFixed(3)));
+}
+
+/**
+ * The notification avatar as an SVG document: a filled disc with the avatar
+ * filling it for custom images or inset for character avatars.
+ *
+ * The inner raster is cover-cropped (`xMidYMid slice`), matching what the web
+ * canvas does, so a portrait or landscape upload fills the square instead of
+ * being letterboxed onto the disc. It is then clipped to the disc, so the disc
+ * edge is the hard boundary no matter how far a cover-crop overflows.
+ *
+ * The `<image href="data:...">` shape is the one `downscaleRaster()` in
+ * `assistant/src/platform/sync-avatar.ts` already feeds resvg, so the daemon's
+ * rasterizer is known to render it.
+ */
+export function notificationAvatarSvg({
+  kind,
+  innerPngBase64,
+  innerMediaType = "image/png",
+  accentHex,
+  size = NOTIFICATION_AVATAR_SIZE,
+}: NotificationAvatarSvgOptions): string {
+  const { radius, offset, inner } = notificationAvatarGeometry(kind, size);
+  const href = `data:${innerMediaType};base64,${innerPngBase64}`;
+  const disc = `cx="${px(radius)}" cy="${px(radius)}" r="${px(radius)}"`;
+  return (
+    `<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" ` +
+    `width="${px(size)}" height="${px(size)}" viewBox="0 0 ${px(size)} ${px(size)}">` +
+    `<circle ${disc} fill="${notificationAvatarDiscHex(accentHex)}"/>` +
+    `<defs><clipPath id="${CLIP_ID}"><circle ${disc}/></clipPath></defs>` +
+    `<image x="${px(offset)}" y="${px(offset)}" width="${px(inner)}" height="${px(inner)}" ` +
+    `preserveAspectRatio="xMidYMid slice" clip-path="url(#${CLIP_ID})" ` +
+    `href="${href}" xlink:href="${href}"/></svg>`
+  );
+}

package/node_modules/@mycadet/avatar-manifest/src/read.ts

@@ -0,0 +1,109 @@
+import {
+  closeSync,
+  constants,
+  existsSync,
+  fstatSync,
+  lstatSync,
+  openSync,
+  readFileSync,
+  realpathSync,
+} from "node:fs";
+import { basename, dirname, join, sep } from "node:path";
+
+import {
+  AVATAR_IMAGE_FILENAME,
+  AVATAR_MANIFEST_FILENAME,
+  AVATAR_TRAITS_FILENAME,
+  resolveAvatarDir,
+} from "./layout.js";
+import { type CharacterTraits, resolveAvatarFromFiles } from "./manifest.js";
+
+export type WorkspaceAvatar =
+  | { kind: "character"; traits: CharacterTraits }
+  | { kind: "image"; imagePath: string }
+  | { kind: "none" };
+
+/** Largest sidecar a host parses; a bigger one counts as absent. */
+export const AVATAR_SIDECAR_MAX_BYTES = 64 * 1024;
+
+function isWithin(root: string, target: string): boolean {
+  return target === root || target.startsWith(root + sep);
+}
+
+/**
+ * Sidecars are read through one validated descriptor: the parent must
+ * resolve beneath the real workspace (a symlinked avatar dir is rejected),
+ * the file must be a regular file at or under the cap, and the open uses
+ * O_NOFOLLOW with a post-open recheck so a swap between check and read
+ * cannot substitute another file. Anything else counts as absent.
+ */
+function readJsonFile(workspaceDir: string, filePath: string): unknown {
+  let fd: number | undefined;
+  try {
+    const realRoot = realpathSync(workspaceDir);
+    const realDir = realpathSync(dirname(filePath));
+    if (!isWithin(realRoot, realDir)) {
+      return undefined;
+    }
+    const realPath = join(realDir, basename(filePath));
+    const linkStats = lstatSync(realPath);
+    if (!linkStats.isFile() || linkStats.size > AVATAR_SIDECAR_MAX_BYTES) {
+      return undefined;
+    }
+    fd = openSync(realPath, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    const stats = fstatSync(fd);
+    if (
+      !stats.isFile() ||
+      stats.dev !== linkStats.dev ||
+      stats.ino !== linkStats.ino ||
+      stats.size > AVATAR_SIDECAR_MAX_BYTES
+    ) {
+      return undefined;
+    }
+    const reopened = realpathSync(filePath);
+    if (!isWithin(realRoot, reopened)) {
+      return undefined;
+    }
+    const reopenedStats = lstatSync(reopened);
+    if (
+      !reopenedStats.isFile() ||
+      reopenedStats.dev !== stats.dev ||
+      reopenedStats.ino !== stats.ino
+    ) {
+      return undefined;
+    }
+    const text = readFileSync(fd, "utf-8");
+    if (Buffer.byteLength(text) > AVATAR_SIDECAR_MAX_BYTES) {
+      return undefined;
+    }
+    return JSON.parse(text) as unknown;
+  } catch {
+    return undefined;
+  } finally {
+    if (fd !== undefined) {
+      closeSync(fd);
+    }
+  }
+}
+
+/**
+ * Reads the avatar of a workspace directly off disk. Unreadable or corrupt
+ * files count as absent. For an image avatar the caller reads the PNG at
+ * `imagePath` itself, applying its own size policy; the file may be missing.
+ */
+export function readWorkspaceAvatar(workspaceDir: string): WorkspaceAvatar {
+  const avatarDir = resolveAvatarDir(workspaceDir);
+  const imagePath = join(avatarDir, AVATAR_IMAGE_FILENAME);
+  const resolved = resolveAvatarFromFiles({
+    manifestJson: readJsonFile(
+      workspaceDir,
+      join(avatarDir, AVATAR_MANIFEST_FILENAME),
+    ),
+    traitsJson: readJsonFile(
+      workspaceDir,
+      join(avatarDir, AVATAR_TRAITS_FILENAME),
+    ),
+    hasImage: existsSync(imagePath),
+  });
+  return resolved.kind === "image" ? { kind: "image", imagePath } : resolved;
+}

package/node_modules/@mycadet/avatar-manifest/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["bun"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/node_modules/@mycadet/environments/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@mycadet/environments",
+  "version": "0.0.1",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./seeds": "./src/seeds.ts",
+    "./shell": "./src/shell.ts",
+    "./test-path-guard": "./src/test-path-guard.ts"
+  },
+  "scripts": {
+    "typecheck": "bunx tsc --noEmit",
+    "test": "bun test src/"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.11",
+    "typescript": "5.9.3"
+  }
+}

package/node_modules/@mycadet/environments/src/__tests__/cloud-assistant-hub-url.test.ts

@@ -0,0 +1,38 @@
+/**
+ * Pins the environment-to-cloud-hub mapping in one place. Both consumers
+ * (the Capacitor shell's `server.url` and the CLI remote-web edge's
+ * `hubUrl`) read this helper, so this matrix is the single behavioral pin
+ * for the served URLs.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import { cloudAssistantHubUrl, SEEDS } from "../index.js";
+
+describe("cloudAssistantHubUrl", () => {
+  test("cloud environments resolve to their own web origin", () => {
+    expect(cloudAssistantHubUrl("production")).toBe(
+      "https://mycadet.ai/assistant",
+    );
+    expect(cloudAssistantHubUrl("staging")).toBe(
+      "https://staging.mycadet.ai/assistant",
+    );
+  });
+
+  test("every other environment falls back to the dev SPA", () => {
+    for (const name of ["dev", "test", "local", "unknown-env", undefined]) {
+      expect(cloudAssistantHubUrl(name)).toBe(
+        "https://dev.mycadet.ai/assistant",
+      );
+    }
+  });
+
+  test("cloud hub URLs derive from the seed web URLs", () => {
+    for (const name of ["production", "staging"]) {
+      expect(cloudAssistantHubUrl(name)).toBe(
+        `${SEEDS[name].webUrl}/assistant`,
+      );
+    }
+    expect(cloudAssistantHubUrl("local")).toBe(`${SEEDS.dev.webUrl}/assistant`);
+  });
+});

package/node_modules/@mycadet/environments/src/__tests__/install-layout.test.ts

@@ -0,0 +1,98 @@
+/**
+ * Tests for reading an install layout: telling a repo checkout from an
+ * installed package, and locating the `assistant` command that ships with an
+ * install.
+ */
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import { findAssistantCommand, isRepoCheckoutPath } from "../index.js";
+
+let root: string;
+
+beforeEach(() => {
+  root = mkdtempSync(join(tmpdir(), "install-layout-"));
+});
+
+afterEach(() => {
+  rmSync(root, { recursive: true, force: true });
+});
+
+/** Create `<nodeModulesDir>/.bin/assistant` and return its path. */
+function seedCommand(nodeModulesDir: string): string {
+  const binDir = join(nodeModulesDir, ".bin");
+  mkdirSync(binDir, { recursive: true });
+  const command = join(binDir, "assistant");
+  writeFileSync(command, "#!/usr/bin/env bun\n");
+  return command;
+}
+
+describe("isRepoCheckoutPath", () => {
+  test("an installed package is not a checkout", () => {
+    expect(
+      isRepoCheckoutPath(
+        "/Users/x/Library/Application Support/@mycadet/macos/cli/latest/node_modules/@mycadet/assistant/src/index.ts",
+      ),
+    ).toBe(false);
+  });
+
+  test("a repo checkout is", () => {
+    expect(
+      isRepoCheckoutPath("/Users/x/dev/cadet/assistant/src/index.ts"),
+    ).toBe(true);
+  });
+
+  test("a directory merely named node_modules-ish is not enough", () => {
+    expect(
+      isRepoCheckoutPath("/Users/x/node_modules_backup/a/src/index.ts"),
+    ).toBe(true);
+  });
+});
+
+describe("findAssistantCommand", () => {
+  test("finds the command shipped beside an installed package", () => {
+    const nodeModules = join(root, "cli", "latest", "node_modules");
+    const command = seedCommand(nodeModules);
+    const path = join(nodeModules, "@mycadet", "assistant", "src", "index.ts");
+
+    expect(findAssistantCommand(path)).toBe(command);
+  });
+
+  test("prefers a nested install over a hoisted one", () => {
+    const outer = join(root, "node_modules");
+    const outerCommand = seedCommand(outer);
+    const inner = join(outer, "cadet", "node_modules");
+    const innerCommand = seedCommand(inner);
+    const path = join(inner, "@mycadet", "assistant", "src", "index.ts");
+
+    expect(findAssistantCommand(path)).toBe(innerCommand);
+    expect(innerCommand).not.toBe(outerCommand);
+  });
+
+  test("falls back to a hoisted install when the nested one has no command", () => {
+    const outer = join(root, "node_modules");
+    const outerCommand = seedCommand(outer);
+    const inner = join(outer, "cadet", "node_modules");
+    mkdirSync(inner, { recursive: true });
+    const path = join(inner, "@mycadet", "assistant", "src", "index.ts");
+
+    expect(findAssistantCommand(path)).toBe(outerCommand);
+  });
+
+  test("returns null for a repo checkout", () => {
+    expect(
+      findAssistantCommand(join(root, "assistant", "src", "index.ts")),
+    ).toBeNull();
+  });
+
+  test("returns null when the install ships no assistant command", () => {
+    const nodeModules = join(root, "node_modules");
+    mkdirSync(join(nodeModules, ".bin"), { recursive: true });
+    const path = join(nodeModules, "@mycadet", "assistant", "src", "index.ts");
+
+    expect(findAssistantCommand(path)).toBeNull();
+  });
+});