@malmhq/intermesh-cli 0.1.0

package/dist/generation/agent-skill-installer/manifest.ts

@@ -0,0 +1,271 @@
+import { createHash } from 'node:crypto';
+import { access, lstat, readFile, readdir } from 'node:fs/promises';
+import { basename, join, relative, resolve, sep } from 'node:path';
+
+export type InstallerErrorCode =
+  'SKILL_CONFLICT' | 'SKILL_PATH_UNSAFE' | 'SKILL_INSTALLATION_BUSY' | 'SKILL_INSTALLATION_FAILED';
+
+export class SkillInstallerError extends Error {
+  constructor(
+    readonly code: InstallerErrorCode,
+    message: string,
+    readonly hint: string,
+  ) {
+    super(message);
+    this.name = 'SkillInstallerError';
+  }
+}
+
+export interface ManagedManifest {
+  schema_version: '1.0.0';
+  package: string;
+  binary: string;
+  version: string;
+  skills: Record<string, string>;
+}
+
+export interface BundledSuite {
+  sourceRoot: string;
+  packageName: string;
+  binary: string;
+  version: string;
+  skills: Record<string, string>;
+}
+
+export type InstalledSkillState =
+  'installed' | 'missing' | 'outdated' | 'managed_modified' | 'unmanaged';
+
+export interface InstalledSkillInspection {
+  name: string;
+  state: InstalledSkillState;
+  expectedHash: string;
+  actualHash?: string;
+}
+
+const skillNamePattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const binaryPattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const packagePattern = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
+const versionPattern = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+const hashPattern = /^sha256:[a-f0-9]{64}$/;
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+export function validateIdentity(packageName: string, binary: string, version: string): void {
+  if (
+    !packagePattern.test(packageName) ||
+    !binaryPattern.test(binary) ||
+    !versionPattern.test(version)
+  ) {
+    throw new SkillInstallerError(
+      'SKILL_PATH_UNSAFE',
+      'Skill package identity is invalid',
+      'Reinstall or regenerate the CLI package.',
+    );
+  }
+}
+
+export function validateSkillName(name: string): void {
+  if (!skillNamePattern.test(name) || basename(name) !== name) {
+    throw new SkillInstallerError(
+      'SKILL_PATH_UNSAFE',
+      'Skill name is invalid',
+      'Use a lowercase Agent Skill name containing letters, numbers and hyphens.',
+    );
+  }
+}
+
+export function manifestFilename(binary: string): string {
+  if (!binaryPattern.test(binary)) {
+    throw new SkillInstallerError(
+      'SKILL_PATH_UNSAFE',
+      'CLI binary name is invalid',
+      'Reinstall or regenerate the CLI package.',
+    );
+  }
+  return `.${binary}-managed.json`;
+}
+
+export function containedPath(root: string, ...parts: string[]): string {
+  const resolvedRoot = resolve(root);
+  const target = resolve(resolvedRoot, ...parts);
+  if (target !== resolvedRoot && !target.startsWith(`${resolvedRoot}${sep}`)) {
+    throw new SkillInstallerError(
+      'SKILL_PATH_UNSAFE',
+      'Skill path escapes the selected destination',
+      'Choose a safe project directory and retry setup.',
+    );
+  }
+  return target;
+}
+
+async function hashDirectory(root: string, current = root, hash = createHash('sha256')) {
+  const entries = await readdir(current, { withFileTypes: true });
+  entries.sort((left, right) => left.name.localeCompare(right.name));
+  for (const entry of entries) {
+    const path = join(current, entry.name);
+    const info = await lstat(path);
+    if (info.isSymbolicLink()) {
+      throw new SkillInstallerError(
+        'SKILL_PATH_UNSAFE',
+        'Skill directories cannot contain symbolic links',
+        'Replace the symbolic link with regular files and retry.',
+      );
+    }
+    const name = relative(root, path).split(sep).join('/');
+    if (info.isDirectory()) await hashDirectory(root, path, hash);
+    else if (info.isFile())
+      hash
+        .update(name)
+        .update('\0')
+        .update(await readFile(path))
+        .update('\0');
+    else {
+      throw new SkillInstallerError(
+        'SKILL_PATH_UNSAFE',
+        'Skill directories may contain only regular files and directories',
+        'Remove unsupported filesystem entries and retry.',
+      );
+    }
+  }
+  return hash;
+}
+
+export async function hashSkillDirectory(path: string): Promise<string> {
+  const info = await lstat(path);
+  if (!info.isDirectory() || info.isSymbolicLink()) {
+    throw new SkillInstallerError(
+      'SKILL_PATH_UNSAFE',
+      'Skill must be a regular directory',
+      'Replace the Skill with a regular directory and retry.',
+    );
+  }
+  return `sha256:${(await hashDirectory(path)).digest('hex')}`;
+}
+
+export async function inspectBundledSuite(input: {
+  sourceRoot: string;
+  packageName: string;
+  binary: string;
+  version: string;
+}): Promise<BundledSuite> {
+  validateIdentity(input.packageName, input.binary, input.version);
+  const entries = await readdir(input.sourceRoot, { withFileTypes: true });
+  const skills: Record<string, string> = {};
+  for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+    validateSkillName(entry.name);
+    if (!entry.isDirectory() || entry.isSymbolicLink()) {
+      throw new SkillInstallerError(
+        'SKILL_PATH_UNSAFE',
+        'Bundled Skills must be regular directories',
+        'Rebuild the CLI package with regular Skill directories.',
+      );
+    }
+    const skillRoot = containedPath(input.sourceRoot, entry.name);
+    try {
+      await access(containedPath(skillRoot, 'SKILL.md'));
+    } catch {
+      throw new SkillInstallerError(
+        'SKILL_INSTALLATION_FAILED',
+        'A bundled Skill is missing SKILL.md',
+        'Rebuild the CLI package with complete Agent Skill directories.',
+      );
+    }
+    skills[entry.name] = await hashSkillDirectory(skillRoot);
+  }
+  if (Object.keys(skills).length === 0) {
+    throw new SkillInstallerError(
+      'SKILL_INSTALLATION_FAILED',
+      'The CLI package contains no Skills',
+      'Reinstall or regenerate the CLI package.',
+    );
+  }
+  return { ...input, skills };
+}
+
+export function parseManifest(value: unknown, expectedBinary?: string): ManagedManifest {
+  if (
+    !isObject(value) ||
+    value['schema_version'] !== '1.0.0' ||
+    typeof value['package'] !== 'string' ||
+    typeof value['binary'] !== 'string' ||
+    typeof value['version'] !== 'string' ||
+    !isObject(value['skills'])
+  ) {
+    throw new SkillInstallerError(
+      'SKILL_CONFLICT',
+      'The managed Skill manifest is invalid',
+      'Inspect or remove the invalid manifest before retrying setup.',
+    );
+  }
+  validateIdentity(value['package'], value['binary'], value['version']);
+  if (expectedBinary && value['binary'] !== expectedBinary) {
+    throw new SkillInstallerError(
+      'SKILL_CONFLICT',
+      'The managed Skill manifest belongs to another CLI',
+      'Choose another destination or remove the conflicting installation.',
+    );
+  }
+  const skills: Record<string, string> = {};
+  for (const [name, hash] of Object.entries(value['skills'])) {
+    validateSkillName(name);
+    if (typeof hash !== 'string' || !hashPattern.test(hash)) {
+      throw new SkillInstallerError(
+        'SKILL_CONFLICT',
+        'The managed Skill manifest contains an invalid hash',
+        'Inspect or remove the invalid manifest before retrying setup.',
+      );
+    }
+    skills[name] = hash;
+  }
+  return {
+    schema_version: '1.0.0',
+    package: value['package'],
+    binary: value['binary'],
+    version: value['version'],
+    skills,
+  };
+}
+
+export async function readManagedManifest(
+  root: string,
+  binary: string,
+): Promise<ManagedManifest | undefined> {
+  const path = containedPath(root, manifestFilename(binary));
+  try {
+    const info = await lstat(path);
+    if (!info.isFile() || info.isSymbolicLink()) throw new Error('unsafe manifest');
+    return parseManifest(JSON.parse(await readFile(path, 'utf8')), binary);
+  } catch (error) {
+    if (isObject(error) && error['code'] === 'ENOENT') return undefined;
+    if (error instanceof SkillInstallerError) throw error;
+    throw new SkillInstallerError(
+      'SKILL_CONFLICT',
+      'The managed Skill manifest cannot be read safely',
+      'Inspect or remove the invalid manifest before retrying setup.',
+    );
+  }
+}
+
+export async function inspectInstalledSkill(
+  root: string,
+  name: string,
+  expectedHash: string,
+  manifest?: ManagedManifest,
+): Promise<InstalledSkillInspection> {
+  const path = containedPath(root, name);
+  try {
+    const actualHash = await hashSkillDirectory(path);
+    const recordedHash = manifest?.skills[name];
+    if (!recordedHash) return { name, state: 'unmanaged', expectedHash, actualHash };
+    if (actualHash !== recordedHash)
+      return { name, state: 'managed_modified', expectedHash, actualHash };
+    if (actualHash !== expectedHash) return { name, state: 'outdated', expectedHash, actualHash };
+    return { name, state: 'installed', expectedHash, actualHash };
+  } catch (error) {
+    if (isObject(error) && error['code'] === 'ENOENT')
+      return { name, state: 'missing', expectedHash };
+    throw error;
+  }
+}

package/dist/generation/agent-skill-installer/targets.ts

@@ -0,0 +1,169 @@
+import { lstat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { relative, resolve } from 'node:path';
+import {
+  containedPath,
+  inspectInstalledSkill,
+  readManagedManifest,
+  SkillInstallerError,
+  type BundledSuite,
+} from './manifest.ts';
+
+export type AgentTarget = 'codex' | 'claude' | 'opencode' | 'cursor';
+export type InstallScope = 'project' | 'global';
+
+const sharedAgents: AgentTarget[] = ['codex', 'claude', 'opencode', 'cursor'];
+
+export interface SkillDestination {
+  agents: AgentTarget[];
+  scope: InstallScope;
+  root: string;
+  location: string;
+  compatibility?: Array<{ agents: AgentTarget[]; root: string; location: string }>;
+}
+
+export interface DiscoveryCopy {
+  agent: AgentTarget;
+  scope: InstallScope;
+  root: string;
+  location: string;
+  skill: string;
+  state: 'managed' | 'managed_modified' | 'outdated' | 'unmanaged' | 'different_owner';
+}
+
+const projectLocations: Record<AgentTarget, string> = {
+  codex: '.agents/skills',
+  claude: '.claude/skills',
+  opencode: '.opencode/skills',
+  cursor: '.cursor/skills',
+};
+
+const globalLocations: Record<AgentTarget, string> = {
+  codex: '.agents/skills',
+  claude: '.claude/skills',
+  opencode: '.config/opencode/skills',
+  cursor: '.cursor/skills',
+};
+
+function destinationRoot(input: {
+  agent: AgentTarget;
+  scope: InstallScope;
+  projectDir?: string;
+  homeDir: string;
+}): { root: string; location: string } {
+  const location =
+    input.scope === 'project' ? projectLocations[input.agent] : globalLocations[input.agent];
+  if (input.scope === 'project') {
+    if (!input.projectDir) {
+      throw new SkillInstallerError(
+        'SKILL_PATH_UNSAFE',
+        'Project directory is required for project Skill installation',
+        'Provide an explicit project directory and retry setup.',
+      );
+    }
+    return { root: resolve(input.projectDir, location), location };
+  }
+  return { root: resolve(input.homeDir, location), location: `~/${location}` };
+}
+
+export function resolveDestinations(input: {
+  scope: InstallScope;
+  projectDir?: string;
+  homeDir?: string;
+}): SkillDestination[] {
+  const shared = destinationRoot({
+    agent: 'codex',
+    scope: input.scope,
+    ...(input.projectDir ? { projectDir: input.projectDir } : {}),
+    homeDir: input.homeDir ?? homedir(),
+  });
+  const compatibility = (['claude', 'opencode', 'cursor'] as const).map((agent) => ({
+    agents: [agent],
+    ...destinationRoot({
+      agent,
+      scope: input.scope,
+      ...(input.projectDir ? { projectDir: input.projectDir } : {}),
+      homeDir: input.homeDir ?? homedir(),
+    }),
+  }));
+  return [
+    {
+      agents: sharedAgents,
+      scope: input.scope,
+      ...shared,
+      compatibility,
+    },
+  ];
+}
+
+function discoveryDestinations(input: {
+  projectDir: string;
+  homeDir: string;
+}): Array<SkillDestination & { agent: AgentTarget }> {
+  return (['project', 'global'] as const).map((scope) => ({
+    agent: 'codex',
+    agents: sharedAgents,
+    scope,
+    ...destinationRoot({
+      agent: 'codex',
+      scope,
+      projectDir: input.projectDir,
+      homeDir: input.homeDir,
+    }),
+  }));
+}
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await lstat(path);
+    return true;
+  } catch (error) {
+    if (typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT')
+      return false;
+    throw error;
+  }
+}
+
+export async function inspectDiscoveryCopies(input: {
+  suite: BundledSuite;
+  projectDir: string;
+  homeDir?: string;
+}): Promise<DiscoveryCopy[]> {
+  const copies: DiscoveryCopy[] = [];
+  for (const destination of discoveryDestinations({
+    projectDir: resolve(input.projectDir),
+    homeDir: resolve(input.homeDir ?? homedir()),
+  })) {
+    const manifest = await readManagedManifest(destination.root, input.suite.binary);
+    for (const [skill, expectedHash] of Object.entries(input.suite.skills)) {
+      if (!(await exists(containedPath(destination.root, skill)))) continue;
+      const inspection = await inspectInstalledSkill(
+        destination.root,
+        skill,
+        expectedHash,
+        manifest,
+      );
+      let state: DiscoveryCopy['state'];
+      if (!manifest?.skills[skill]) state = 'unmanaged';
+      else if (
+        manifest.package !== input.suite.packageName ||
+        manifest.binary !== input.suite.binary
+      )
+        state = 'different_owner';
+      else if (manifest.version !== input.suite.version) state = 'outdated';
+      else state = inspection.state === 'installed' ? 'managed' : 'managed_modified';
+      copies.push({
+        agent: destination.agent,
+        scope: destination.scope,
+        root: destination.root,
+        location:
+          destination.scope === 'global'
+            ? destination.location
+            : relative(input.projectDir, destination.root) || '.',
+        skill,
+        state,
+      });
+    }
+  }
+  return copies;
+}