@anhlp/alp-core 0.0.0-beta.1

package/package.json

@@ -0,0 +1,309 @@
+{
+  "name": "@anhlp/alp-core",
+  "version": "0.0.0-beta.1",
+  "type": "module",
+  "description": "ALP core module",
+  "files": [
+    "src",
+    "dist",
+    "templates",
+    "NOTICE"
+  ],
+  "exports": {
+    "./adapter": {
+      "alp-source": {
+        "types": "./src/adapter.js",
+        "default": "./src/adapter.js"
+      },
+      "types": "./dist/adapter.d.ts",
+      "default": "./src/adapter.js"
+    },
+    "./atomic": {
+      "alp-source": {
+        "types": "./src/atomic.js",
+        "default": "./src/atomic.js"
+      },
+      "types": "./dist/atomic.d.ts",
+      "default": "./src/atomic.js"
+    },
+    "./backup": {
+      "alp-source": {
+        "types": "./src/backup.js",
+        "default": "./src/backup.js"
+      },
+      "types": "./dist/backup.d.ts",
+      "default": "./src/backup.js"
+    },
+    "./beads": {
+      "alp-source": {
+        "types": "./src/beads.js",
+        "default": "./src/beads.js"
+      },
+      "types": "./dist/beads.d.ts",
+      "default": "./src/beads.js"
+    },
+    "./delegation": {
+      "alp-source": {
+        "types": "./src/delegation.js",
+        "default": "./src/delegation.js"
+      },
+      "types": "./dist/delegation.d.ts",
+      "default": "./src/delegation.js"
+    },
+    "./errors": {
+      "alp-source": {
+        "types": "./src/errors.js",
+        "default": "./src/errors.js"
+      },
+      "types": "./dist/errors.d.ts",
+      "default": "./src/errors.js"
+    },
+    "./formulas": {
+      "alp-source": {
+        "types": "./src/formulas.js",
+        "default": "./src/formulas.js"
+      },
+      "types": "./dist/formulas.d.ts",
+      "default": "./src/formulas.js"
+    },
+    "./hook-run": {
+      "alp-source": {
+        "types": "./src/hook-run.js",
+        "default": "./src/hook-run.js"
+      },
+      "types": "./dist/hook-run.d.ts",
+      "default": "./src/hook-run.js"
+    },
+    "./hooks": {
+      "alp-source": {
+        "types": "./src/hooks.js",
+        "default": "./src/hooks.js"
+      },
+      "types": "./dist/hooks.d.ts",
+      "default": "./src/hooks.js"
+    },
+    "./index": {
+      "alp-source": {
+        "types": "./src/index.js",
+        "default": "./src/index.js"
+      },
+      "types": "./dist/index.d.ts",
+      "default": "./src/index.js"
+    },
+    ".": {
+      "alp-source": {
+        "types": "./src/index.js",
+        "default": "./src/index.js"
+      },
+      "types": "./dist/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./init": {
+      "alp-source": {
+        "types": "./src/init.js",
+        "default": "./src/init.js"
+      },
+      "types": "./dist/init.d.ts",
+      "default": "./src/init.js"
+    },
+    "./library-edit": {
+      "alp-source": {
+        "types": "./src/library-edit.js",
+        "default": "./src/library-edit.js"
+      },
+      "types": "./dist/library-edit.d.ts",
+      "default": "./src/library-edit.js"
+    },
+    "./library": {
+      "alp-source": {
+        "types": "./src/library.js",
+        "default": "./src/library.js"
+      },
+      "types": "./dist/library.d.ts",
+      "default": "./src/library.js"
+    },
+    "./log": {
+      "alp-source": {
+        "types": "./src/log.js",
+        "default": "./src/log.js"
+      },
+      "types": "./dist/log.d.ts",
+      "default": "./src/log.js"
+    },
+    "./migrations": {
+      "alp-source": {
+        "types": "./src/migrations.js",
+        "default": "./src/migrations.js"
+      },
+      "types": "./dist/migrations.d.ts",
+      "default": "./src/migrations.js"
+    },
+    "./models": {
+      "alp-source": {
+        "types": "./src/models.js",
+        "default": "./src/models.js"
+      },
+      "types": "./dist/models.d.ts",
+      "default": "./src/models.js"
+    },
+    "./permissions": {
+      "alp-source": {
+        "types": "./src/permissions.js",
+        "default": "./src/permissions.js"
+      },
+      "types": "./dist/permissions.d.ts",
+      "default": "./src/permissions.js"
+    },
+    "./profiles": {
+      "alp-source": {
+        "types": "./src/profiles.js",
+        "default": "./src/profiles.js"
+      },
+      "types": "./dist/profiles.d.ts",
+      "default": "./src/profiles.js"
+    },
+    "./promptsafe": {
+      "alp-source": {
+        "types": "./src/promptsafe.js",
+        "default": "./src/promptsafe.js"
+      },
+      "types": "./dist/promptsafe.d.ts",
+      "default": "./src/promptsafe.js"
+    },
+    "./providers": {
+      "alp-source": {
+        "types": "./src/providers.js",
+        "default": "./src/providers.js"
+      },
+      "types": "./dist/providers.d.ts",
+      "default": "./src/providers.js"
+    },
+    "./resolver": {
+      "alp-source": {
+        "types": "./src/resolver.js",
+        "default": "./src/resolver.js"
+      },
+      "types": "./dist/resolver.d.ts",
+      "default": "./src/resolver.js"
+    },
+    "./state-schema": {
+      "alp-source": {
+        "types": "./src/state-schema.js",
+        "default": "./src/state-schema.js"
+      },
+      "types": "./dist/state-schema.d.ts",
+      "default": "./src/state-schema.js"
+    },
+    "./task-rows": {
+      "alp-source": {
+        "types": "./src/task-rows.js",
+        "default": "./src/task-rows.js"
+      },
+      "types": "./dist/task-rows.d.ts",
+      "default": "./src/task-rows.js"
+    },
+    "./tasks": {
+      "alp-source": {
+        "types": "./src/tasks.js",
+        "default": "./src/tasks.js"
+      },
+      "types": "./dist/tasks.d.ts",
+      "default": "./src/tasks.js"
+    },
+    "./teams": {
+      "alp-source": {
+        "types": "./src/teams.js",
+        "default": "./src/teams.js"
+      },
+      "types": "./dist/teams.d.ts",
+      "default": "./src/teams.js"
+    },
+    "./trust": {
+      "alp-source": {
+        "types": "./src/trust.js",
+        "default": "./src/trust.js"
+      },
+      "types": "./dist/trust.d.ts",
+      "default": "./src/trust.js"
+    },
+    "./upgrade": {
+      "alp-source": {
+        "types": "./src/upgrade.js",
+        "default": "./src/upgrade.js"
+      },
+      "types": "./dist/upgrade.d.ts",
+      "default": "./src/upgrade.js"
+    },
+    "./user-settings": {
+      "alp-source": {
+        "types": "./src/user-settings.js",
+        "default": "./src/user-settings.js"
+      },
+      "types": "./dist/user-settings.d.ts",
+      "default": "./src/user-settings.js"
+    },
+    "./validation": {
+      "alp-source": {
+        "types": "./src/validation.js",
+        "default": "./src/validation.js"
+      },
+      "types": "./dist/validation.d.ts",
+      "default": "./src/validation.js"
+    },
+    "./verify": {
+      "alp-source": {
+        "types": "./src/verify.js",
+        "default": "./src/verify.js"
+      },
+      "types": "./dist/verify.d.ts",
+      "default": "./src/verify.js"
+    },
+    "./workflow": {
+      "alp-source": {
+        "types": "./src/workflow.js",
+        "default": "./src/workflow.js"
+      },
+      "types": "./dist/workflow.d.ts",
+      "default": "./src/workflow.js"
+    },
+    "./types": {
+      "alp-source": {
+        "types": "./src/types.d.ts"
+      },
+      "types": "./dist/types.d.ts"
+    },
+    "./template-path": {
+      "alp-source": {
+        "types": "./src/template-path.js"
+      },
+      "types": "./dist/template-path.d.ts",
+      "default": "./src/template-path.js"
+    }
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "dependencies": {
+    "@anhlp/alp-protocol": "0.0.0-beta.1"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build-workspace.mjs core",
+    "test": "node ../../scripts/test-package.mjs core",
+    "prepack": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "tag": "beta"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/phucanh08/alp.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/phucanh08/alp/tree/main/packages/core#readme",
+  "bugs": {
+    "url": "https://github.com/phucanh08/alp/issues"
+  }
+}

package/src/adapter.d.ts

@@ -0,0 +1,20 @@
+import type { ResolvedAgent } from './types.js';
+export type CapabilitySupport = 'native' | 'emulated' | 'unsupported';
+export interface AdapterCapabilities {
+  instructions: CapabilitySupport;
+  skills: CapabilitySupport;
+  hooks: CapabilitySupport;
+  mcp: CapabilitySupport;
+}
+export interface CompiledAgent<T = unknown> {
+  adapterId: string;
+  agentName: string;
+  projectRoot: string;
+  material: T;
+}
+export interface AlpRuntimeAdapter<T = unknown> {
+  id: string;
+  capabilities(): AdapterCapabilities;
+  compile(agent: ResolvedAgent): Promise<CompiledAgent<T>>;
+}
+export function compileAgent<T>(adapter: AlpRuntimeAdapter<T>, agent: ResolvedAgent): Promise<CompiledAgent<T>>;

package/src/adapter.js

@@ -0,0 +1,29 @@
+import { AlpError } from './errors.js';
+import { validateResolvedAgent } from './validation.js';
+
+/** Validate a plugin boundary before handing off the provider-neutral IR. */
+export async function compileAgent(adapter, agent) {
+  if (!adapter || typeof adapter.id !== 'string' || !adapter.id.trim() || typeof adapter.capabilities !== 'function' || typeof adapter.compile !== 'function') {
+    throw new AlpError('INVALID_ADAPTER', 'Adapter requires id, capabilities(), and compile()');
+  }
+  validateResolvedAgent(agent);
+  const capabilities = adapter.capabilities();
+  for (const key of ['instructions', 'skills', 'hooks', 'mcp']) {
+    if (!['native', 'emulated', 'unsupported'].includes(capabilities?.[key])) throw new AlpError('INVALID_CAPABILITIES', `${adapter.id}: invalid ${key} capability`);
+  }
+  const required = {
+    instructions: Boolean(agent.instructions.project || agent.instructions.agent),
+    skills: agent.skills.length > 0,
+    hooks: agent.hooks.length > 0,
+    mcp: Object.keys(agent.mcp.mcpServers).length > 0,
+  };
+  for (const [key, present] of Object.entries(required)) {
+    if (present && capabilities[key] === 'unsupported') throw new AlpError('UNSUPPORTED_CAPABILITY', `${adapter.id} does not support ${key} required by '${agent.name}'`);
+  }
+  // Adapters receive their own snapshot; compilation must not mutate the resolved source.
+  const compiled = await adapter.compile(structuredClone(agent));
+  if (!compiled || compiled.adapterId !== adapter.id || compiled.agentName !== agent.name || compiled.projectRoot !== agent.projectRoot || !Object.hasOwn(compiled, 'material')) {
+    throw new AlpError('INVALID_COMPILED_AGENT', `${adapter.id}: invalid compiled agent envelope`);
+  }
+  return compiled;
+}

package/src/atomic.d.ts

@@ -0,0 +1,2 @@
+export function moveFile(from: string, to: string): Promise<void>;
+export function writeAtomic(file: string, body: string | Uint8Array, mode?: number): Promise<void>;

package/src/atomic.js

@@ -0,0 +1,28 @@
+import { randomBytes } from 'node:crypto';
+import { rename, rm, writeFile } from 'node:fs/promises';
+
+/**
+ * Moves `from` to `to`. On Windows the move fails with EPERM, EACCES or EBUSY while another
+ * process has the target open, such as a client reading it; it is tried again then.
+ */
+export async function moveFile(from, to) {
+  for (let attempt = 0; ; attempt++) {
+    try { return await rename(from, to); }
+    catch (error) {
+      if (process.platform !== 'win32' || attempt >= 20 || !['EPERM', 'EACCES', 'EBUSY'].includes(error?.code)) throw error;
+      await new Promise(resolve => setTimeout(resolve, 10 + attempt * 10));
+    }
+  }
+}
+
+/** Writes `file` through a temporary file beside it, so a reader sees the old or the new content. */
+export async function writeAtomic(file, body, mode = 0o600) {
+  const temporary = `${file}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
+  try {
+    await writeFile(temporary, body, { mode });
+    await moveFile(temporary, file);
+  } catch (error) {
+    await rm(temporary, { force: true }).catch(() => {});
+    throw error;
+  }
+}

package/src/backup.d.ts

@@ -0,0 +1,27 @@
+export const BACKUP_FORMAT: number;
+export const BACKUP_EXTENSION: string;
+export const STATE_UNITS: string[];
+export const CLEARED_UNITS: string[];
+export const HOME_UNITS: string[];
+export const PROJECT_UNITS: string[];
+export function backupsDir(home: string): string;
+export function knownProjects(home: string): Promise<string[]>;
+export type BackupSummary = { file: string; files: number; bytes: number; projects: string[]; stateSchema: number | null; sessions: number; tasks: number };
+export function createBackup(options: { home: string; out: string; units?: string[]; projects?: string[]; by?: string; kind?: string }): Promise<BackupSummary>;
+export function automaticBackup(home: string, kind: string, options?: { units?: string[]; projects?: string[]; by?: string }): Promise<string>;
+export type BackupContents = { file: string; kind: string; by?: string; createdAt: string; home: string; stateSchema: number | null; units: string[]; projects: string[]; sessions: number; tasks: number; files: number; bytes: number; external: number };
+export function verifyBackup(file: string): Promise<BackupContents>;
+export function recoverInterruptedRestore(home: string): Promise<{ outcome: 'rolled back' | 'completed'; file?: string; safety?: string } | undefined>;
+export type RestoreResult = {
+  file: string;
+  safety?: string;
+  stateSchema: number | null;
+  interrupted?: { outcome: 'rolled back' | 'completed'; file?: string; safety?: string };
+  units: Array<{ area: string; unit: string; present: boolean }>;
+  projects: string[];
+  skipped: Array<{ root: string; reason: string }>;
+  warnings: string[];
+};
+export function restoreBackup(options: { home: string; file: string; projects?: boolean; safety?: boolean; clearLive?: boolean; replaceNewer?: boolean; by?: string; beforeSwap?: (index: number, total: number) => Promise<void> | void }): Promise<RestoreResult>;
+export function readRestoredMarker(home: string): Promise<{ at?: string; from?: string; by?: string } | undefined>;
+export function clearRestoredMarker(home: string): Promise<void>;