@makaio/framework 1.0.0-dev-1781022866275 → 1.0.0-dev-1781023871421

package/dist/utils/index.d.mts

@@ -0,0 +1,262 @@
+//#region packages/utils/src/deferred-promise.d.ts
+declare class DeferredPromise<T> {
+  private deferred;
+  private isTracked;
+  getPromise(): Promise<T>;
+  resolve(value: T): void;
+  reject(error: Error): void;
+}
+//#endregion
+//#region packages/utils/src/cli.d.ts
+/** Exit codes shared by framework CLI commands. */
+declare const CLI_EXIT_CODES: {
+  /** Generic command failure. */readonly failure: 1; /** GNU `timeout` convention. */
+  readonly timeout: 124; /** Shell Ctrl-C convention. */
+  readonly abort: 130;
+};
+/** Process signals that should abort a local CLI command cooperatively. */
+declare const CLI_COMMAND_ABORT_SIGNALS: readonly ["SIGINT", "SIGTERM", "SIGHUP"];
+/** Signal-specific shell exit codes for cooperative CLI command shutdown. */
+declare const CLI_COMMAND_SIGNAL_EXIT_CODES: Record<(typeof CLI_COMMAND_ABORT_SIGNALS)[number], number>;
+/** Known command error categories that map to stable CLI exit codes. */
+type CliCommandErrorKind = 'abort' | 'timeout' | 'failure';
+/**
+ * Read all stdin bytes when input is piped into the process.
+ * @param signal - Optional command abort signal that cancels the stdin read.
+ * @returns The stdin content, or `null` when stdin is attached to a TTY.
+ */
+declare function readStdin(signal?: AbortSignal): Promise<string | null>;
+/**
+ * Classify bus wait errors for user-facing CLI handling.
+ *
+ * Uses the stable error `name` instead of importing bus-core error classes so
+ * this package remains a zero-internal-dependency utility layer.
+ * @param error - Caught command error.
+ * @returns The CLI error category.
+ */
+declare function classifyCliCommandError(error: unknown): CliCommandErrorKind;
+/**
+ * Resolve a process-signal abort reason to its conventional CLI exit code.
+ * @param reason - AbortSignal reason captured from the process signal handler.
+ * @returns Signal-specific exit code, or `undefined` when the reason is not a known command signal.
+ */
+declare function resolveCliSignalExitCode(reason: unknown): number | undefined;
+//#endregion
+//#region packages/utils/src/is-record.d.ts
+/**
+ * Check whether a value is a non-array object (a "record").
+ * @param value - Value to check.
+ * @returns True when the value is a plain record.
+ */
+declare function isRecord(value: unknown): value is Record<string, unknown>;
+//#endregion
+//#region packages/utils/src/extract-json.d.ts
+/**
+ * Extract a JSON object from text that may contain surrounding content.
+ *
+ * LLM responses often wrap JSON in markdown fences or prose. This function
+ * finds the first `{` and last `}` in the text and returns the substring
+ * between them (inclusive).
+ *
+ * Returns the original text unchanged when no valid brace pair is found.
+ * @param text - Raw text potentially containing a JSON object
+ * @returns Extracted JSON substring, or the original text if no braces found
+ */
+declare function extractJson(text: string): string;
+//#endregion
+//#region packages/utils/src/getErrorString.d.ts
+/**
+ * Extracts error message string from various error types
+ * @param error - Error value to extract message from
+ * @returns Error message string or 'Unknown error'
+ */
+declare function getErrorString(error: string | Error | undefined): string;
+//#endregion
+//#region packages/utils/src/normalize-bus-secret.d.ts
+/**
+ * Shared normalization for the `MAKAIO_BUS_SECRET` environment variable.
+ *
+ * Applies consistent trim-and-reject logic so every entry-point (CLI serve,
+ * config provider, …) behaves identically when reading the secret.
+ */
+/**
+ * Normalize a raw `MAKAIO_BUS_SECRET` value.
+ *
+ * - `undefined` (variable unset) → returns `undefined`
+ * - Non-empty string after trimming → returns the trimmed value
+ * - Empty string or whitespace-only → throws, because a secret that collapses
+ *   to the empty string is almost certainly a misconfiguration and must not
+ *   silently fall back to unauthenticated mode.
+ * @param raw - The raw environment variable value, or `undefined` when unset.
+ * @returns The trimmed secret string, or `undefined` when the variable is unset.
+ * @throws When the variable is set but evaluates to an empty string after trimming.
+ */
+declare function normalizeBusSecret(raw: string | undefined): string | undefined;
+//#endregion
+//#region packages/utils/src/runtime.d.ts
+/**
+ * Runtime detection utilities.
+ *
+ * Provides a single, canonical implementation of runtime checks used across
+ * framework packages and host extensions.
+ * @packageDocumentation
+ */
+/**
+ * Returns `true` when the current process is running under the Bun runtime.
+ *
+ * Detection is based on the presence of the `Bun` property on `globalThis`,
+ * which Bun always exposes. Uses a bracket-access check to avoid a TypeScript
+ * error on environments where the `Bun` global is not declared.
+ * @returns Whether the current runtime is Bun.
+ */
+declare function isBunRuntime(): boolean;
+//#endregion
+//#region packages/utils/src/safe-stringify.d.ts
+/**
+ * JSON-stringify a value, handling BigInt and circular references gracefully.
+ * @param value - Value to serialize.
+ * @returns JSON string, never throws.
+ */
+declare function safeStringify(value: unknown): string;
+//#endregion
+//#region packages/utils/src/timeout/types.d.ts
+/**
+ * Timeout configuration types for AI adapter operations.
+ *
+ * Each category represents a distinct phase with different performance
+ * characteristics and failure modes.
+ */
+/**
+ * Categories of timeouts in the adapter lifecycle.
+ */
+type TimeoutCategory = 'initialization' | 'acknowledgement' | 'completion' | 'toolApproval' | 'eventWait';
+/**
+ * Complete timeout configuration where all categories are required.
+ * Used by adapters to declare their mandatory defaults.
+ */
+type RequiredTimeoutConfig = Record<TimeoutCategory, number>;
+/**
+ * Layer that provided a timeout value (for provenance tracking).
+ */
+type TimeoutLayer = 'global' | 'adapter' | 'runtime' | 'call';
+/**
+ * Provenance tracking: which layer set each timeout value.
+ */
+type TimeoutSources = Record<TimeoutCategory, {
+  layer: TimeoutLayer;
+  source: string;
+}>;
+/**
+ * Resolved timeout configuration with provenance tracking.
+ * Enables debugging "why is this timeout X?"
+ */
+interface TrackedTimeoutConfig {
+  /** Resolved timeout values in milliseconds */
+  values: RequiredTimeoutConfig;
+  /** Source information for each timeout value */
+  sources: TimeoutSources;
+}
+/**
+ * Global default timeout values (milliseconds).
+ *
+ * Philosophy:
+ * - initialization: Allow time for cold starts and auth
+ * - acknowledgement: Fast feedback that message was received
+ * - completion: Account for complex reasoning
+ * - toolApproval: Short for responsiveness (user is waiting)
+ * - eventWait: Default for once() calls waiting for events
+ */
+declare const DEFAULT_TIMEOUTS: RequiredTimeoutConfig;
+/**
+ * All timeout categories as array (for iteration).
+ */
+declare const TIMEOUT_CATEGORIES: readonly TimeoutCategory[];
+/**
+ * Partial timeout configuration for user overrides.
+ * All fields are optional - missing values inherit from lower layers.
+ */
+type TimeoutConfig = Partial<RequiredTimeoutConfig>;
+//#endregion
+//#region packages/utils/src/timeout/resolve.d.ts
+/**
+ * Input for a single layer in the timeout resolution chain.
+ */
+interface TimeoutLayerInput {
+  /** Which layer this config comes from */
+  layer: TimeoutLayer;
+  /** Human-readable source identifier (e.g., 'openai-node', 'config.ts') */
+  source: string;
+  /** Partial timeout config - undefined values are skipped */
+  config: TimeoutConfig | undefined;
+}
+/**
+ * Resolve timeout configuration by merging layers in order.
+ *
+ * Resolution order (later overrides earlier):
+ * 1. Global defaults (DEFAULT_TIMEOUTS)
+ * 2. Adapter defaults (from adapterDefinition.defaultTimeouts)
+ * 3. Runtime config (from adapter config.ts / environment)
+ * 4. Per-call overrides (passed to individual operations)
+ * @param layers - Array of layer inputs to merge
+ * @returns TrackedTimeoutConfig with resolved values and provenance
+ * @example
+ * ```typescript
+ * const timeouts = resolveTimeouts([
+ *   { layer: 'adapter', source: 'openai-node', config: adapterDefinition.defaultTimeouts },
+ *   { layer: 'runtime', source: 'config.ts', config: runtimeOverrides },
+ * ]);
+ * // timeouts.values.completion -> resolved value
+ * // timeouts.sources.completion -> { layer: 'adapter', source: 'openai-node' }
+ * ```
+ */
+declare function resolveTimeouts(layers: TimeoutLayerInput[]): TrackedTimeoutConfig;
+/**
+ * Debug helper: explain why a timeout has its current value.
+ * @param tracked - Resolved timeout config with provenance
+ * @param category - Which timeout category to explain
+ * @returns Human-readable explanation string
+ * @example
+ * ```typescript
+ * console.debug(explainTimeout(timeouts, 'completion'));
+ * // "completion=120000ms (from adapter: openai-node)"
+ * ```
+ */
+declare function explainTimeout(tracked: TrackedTimeoutConfig, category: TimeoutCategory): string;
+/**
+ * Debug helper: explain all timeout values and their sources.
+ * @param tracked - Resolved timeout config with provenance
+ * @returns Multi-line string with all timeouts explained
+ */
+declare function explainAllTimeouts(tracked: TrackedTimeoutConfig): string;
+//#endregion
+//#region packages/utils/src/timeout/signal.d.ts
+/**
+ * An AbortSignal paired with a cleanup handle for its backing timer.
+ */
+interface TimeoutSignal {
+  /** AbortSignal that aborts when the timeout elapses. */
+  signal: AbortSignal;
+  /** Cancel the backing timer before it fires, preventing the abort. */
+  clear: () => void;
+}
+/**
+ * Create an `AbortSignal` that aborts after `timeoutMs` milliseconds.
+ *
+ * Always call {@link TimeoutSignal.clear} in a `finally` block to prevent
+ * the timer from leaking when the guarded operation completes before the
+ * timeout elapses.
+ * @param timeoutMs - Timeout duration in milliseconds.
+ * @returns A {@link TimeoutSignal} containing the signal and a `clear` callback.
+ * @example
+ * ```typescript
+ * const timeout = createTimeoutSignal(5_000);
+ * try {
+ *   const response = await fetch(url, { signal: timeout.signal });
+ * } finally {
+ *   timeout.clear();
+ * }
+ * ```
+ */
+declare function createTimeoutSignal(timeoutMs: number): TimeoutSignal;
+//#endregion
+export { CLI_COMMAND_ABORT_SIGNALS, CLI_COMMAND_SIGNAL_EXIT_CODES, CLI_EXIT_CODES, type CliCommandErrorKind, DEFAULT_TIMEOUTS, DeferredPromise, type RequiredTimeoutConfig, TIMEOUT_CATEGORIES, type TimeoutCategory, type TimeoutConfig, type TimeoutLayer, type TimeoutLayerInput, type TimeoutSignal, type TimeoutSources, type TrackedTimeoutConfig, classifyCliCommandError, createTimeoutSignal, explainAllTimeouts, explainTimeout, extractJson, getErrorString, isBunRuntime, isRecord, normalizeBusSecret, readStdin, resolveCliSignalExitCode, resolveTimeouts, safeStringify };

package/dist/utils/index.mjs

@@ -0,0 +1,2 @@
+function e(){let e={};return e.promise=new Promise((t,n)=>{e.resolve=t,e.reject=n}),e}var t=class{deferred=e();isTracked=!1;getPromise(){return this.isTracked=!0,this.deferred.promise}resolve(e){this.deferred.resolve(e)}reject(e){this.isTracked&&this.deferred.reject(e)}};const n={failure:1,timeout:124,abort:130},r=[`SIGINT`,`SIGTERM`,`SIGHUP`],i={SIGINT:130,SIGTERM:143,SIGHUP:129};async function a(e){if(process.stdin.isTTY)return null;if(e?.aborted===!0)throw c(e.reason);let t=[],n=process.stdin,r=(async()=>{for await(let e of n)t.push(Buffer.from(e));return Buffer.concat(t).toString(`utf-8`)})();if(r.catch(()=>void 0),e===void 0)return await r;let i,a=new Promise((t,r)=>{i=()=>{let t=c(e.reason);n.destroy(t),r(t)},e.addEventListener(`abort`,i,{once:!0})});try{return await Promise.race([r,a])}finally{i!==void 0&&e.removeEventListener(`abort`,i)}}function o(e){return e instanceof Error&&e.name===`OnceAbortError`?`abort`:e instanceof Error&&e.name===`OnceTimeoutError`?`timeout`:`failure`}function s(e){return typeof e==`string`&&Object.hasOwn(i,e)?i[e]:void 0}function c(e){let t=Error(e===void 0?`Command aborted`:String(e));return t.name=`OnceAbortError`,t}function l(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function u(e){let t=e.indexOf(`{`),n=e.lastIndexOf(`}`);return t===-1||n===-1||n<=t?e:e.slice(t,n+1)}function d(e){return e?typeof e==`string`?e:e.message||`Unknown error`:`Unknown error`}function f(e){if(e===void 0)return;let t=e.trim();if(t===``)throw Error(`MAKAIO_BUS_SECRET is set but empty after trimming; refusing to use an empty secret`);return t}function p(){return globalThis.Bun!==void 0}function m(e){if(e===void 0)return`null`;let t=[];try{return JSON.stringify(e,function(e,n){if(typeof n==`bigint`)return n.toString();for(;t.length>0&&t[t.length-1]!==this;)t.pop();if(typeof n==`object`&&n){if(t.includes(n))return`[Circular]`;t.push(n)}return n})??JSON.stringify(String(e))??`"[Unserializable]"`}catch{try{return JSON.stringify(String(e))??`"[Unserializable]"`}catch{return`"[Unserializable]"`}}}const h={initialization:3e4,acknowledgement:3e4,completion:6e4,toolApproval:5e3,eventWait:1e4},g=[`initialization`,`acknowledgement`,`completion`,`toolApproval`,`eventWait`];function _(e){let t={...h},n={};for(let e of g)n[e]={layer:`global`,source:`DEFAULT_TIMEOUTS`};for(let{layer:r,source:i,config:a}of e)if(a)for(let e of g){let o=a[e];o!==void 0&&(t[e]=o,n[e]={layer:r,source:i})}return{values:t,sources:n}}function v(e,t){let{layer:n,source:r}=e.sources[t];return`${t}=${e.values[t]}ms (from ${n}: ${r})`}function y(e){return g.map(t=>v(e,t)).join(`
+`)}function b(e){let t=new AbortController,n=setTimeout(()=>t.abort(),e);return{signal:t.signal,clear:()=>clearTimeout(n)}}export{r as CLI_COMMAND_ABORT_SIGNALS,i as CLI_COMMAND_SIGNAL_EXIT_CODES,n as CLI_EXIT_CODES,h as DEFAULT_TIMEOUTS,t as DeferredPromise,g as TIMEOUT_CATEGORIES,o as classifyCliCommandError,b as createTimeoutSignal,y as explainAllTimeouts,v as explainTimeout,u as extractJson,d as getErrorString,p as isBunRuntime,l as isRecord,f as normalizeBusSecret,a as readStdin,s as resolveCliSignalExitCode,_ as resolveTimeouts,m as safeStringify};

package/dist/utils/keychain.d.mts

@@ -0,0 +1,31 @@
+//#region packages/utils/src/keychain.d.ts
+/**
+ * Reads a generic password from the macOS keychain.
+ *
+ * Uses `/usr/bin/security` directly with argv arrays so shell expansion is not
+ * involved. Returns `null` when the entry does not exist.
+ * @param service - Keychain service name.
+ * @param account - Optional keychain account name.
+ * @returns Stored password value, or `null` when absent.
+ */
+declare function keychainRead(service: string, account?: string): Promise<string | null>;
+/**
+ * Writes a generic password to the macOS keychain.
+ *
+ * Uses `-U` to update existing entries and `-X` so arbitrary UTF-8 JSON values
+ * round-trip without shell quoting or locale assumptions.
+ * @param service - Keychain service name.
+ * @param account - Keychain account name.
+ * @param value - Password value to store.
+ */
+declare function keychainWrite(service: string, account: string, value: string): Promise<void>;
+/**
+ * Deletes a generic password from the macOS keychain.
+ *
+ * Missing entries are treated as already deleted.
+ * @param service - Keychain service name.
+ * @param account - Optional keychain account name.
+ */
+declare function keychainDelete(service: string, account?: string): Promise<void>;
+//#endregion
+export { keychainDelete, keychainRead, keychainWrite };

package/dist/utils/keychain.mjs

@@ -0,0 +1 @@
+import{execFile as e}from"node:child_process";import{promisify as t}from"node:util";const n=t(e);function r(e){let t=/^password: 0x([0-9A-Fa-f]+)/m.exec(e);if(t)return Buffer.from(t[1],`hex`).toString(`utf-8`);let n=/^password: "(.*)"/m.exec(e);if(n)return n[1];let r=e.replace(/^password:.*$/gm,`password: [REDACTED]`);throw Error(`Unexpected security output format: ${r}`)}async function i(e,t){let i=[`find-generic-password`,`-s`,e,`-g`];t&&i.push(`-a`,t);try{let{stderr:e}=await n(`/usr/bin/security`,i);return r(e)}catch(e){if(e instanceof Error){let t=e.code;if(t===`ENOENT`)throw e;if(t===44)return null}throw e}}async function a(e,t,r){await n(`/usr/bin/security`,[`add-generic-password`,`-U`,`-s`,e,`-a`,t,`-X`,Buffer.from(r,`utf-8`).toString(`hex`)])}async function o(e,t){let r=[`delete-generic-password`,`-s`,e];t&&r.push(`-a`,t);try{await n(`/usr/bin/security`,r)}catch(e){if(e instanceof Error){let t=e.code;if(t===`ENOENT`)throw e;if(t===44)return}throw e}}export{o as keychainDelete,i as keychainRead,a as keychainWrite};

package/dist/utils/project-manifest.d.mts

@@ -0,0 +1,130 @@
+import { z } from "zod";
+
+//#region packages/utils/src/project-manifest.d.ts
+/** Basename of the project manifest file within the Makaio project directory. */
+declare const PROJECT_MANIFEST_BASENAME = "manifest.json";
+/**
+ * Relative path from a repository root to the project manifest file.
+ * For example, `.makaio/manifest.json`.
+ */
+declare const PROJECT_MANIFEST_FILE: string;
+/** Schema identifier used in the `$schema` field of the manifest. */
+declare const PROJECT_MANIFEST_SCHEMA_ID = "makaio/project-manifest/v1";
+/**
+ * A parsed extension spec that has been validated to contain an exact semantic version.
+ */
+interface ExactExtensionSpec {
+  /** Fully-qualified npm package name (e.g. `@makaio/extension-workflow`). */
+  readonly packageName: string;
+  /** Exact semantic version string (e.g. `0.1.4`). */
+  readonly version: string;
+  /** Original spec string passed by the caller (e.g. `@makaio/extension-workflow@0.1.4`). */
+  readonly spec: string;
+}
+/** Installed extension version shape used when comparing a project manifest with local state. */
+interface InstalledExtensionVersion {
+  /** npm package name without any version suffix. */
+  readonly name: string;
+  /** Installed package version. */
+  readonly version: string;
+}
+/** A manifest pin that is already installed at the requested version. */
+interface SatisfiedProjectManifestExtension {
+  /** Parsed exact manifest pin. */
+  readonly manifest: ExactExtensionSpec;
+  /** Installed version matching the manifest pin. */
+  readonly installedVersion: string;
+}
+/** A manifest pin whose package is installed at a different version. */
+interface MismatchedProjectManifestExtension {
+  /** Parsed exact manifest pin. */
+  readonly manifest: ExactExtensionSpec;
+  /** Version currently installed in the singleton Makaio home. */
+  readonly installedVersion: string;
+}
+/** Comparison result for project manifest extension pins against installed state. */
+interface ProjectManifestExtensionDiff {
+  /** Manifest pins already satisfied by installed state. */
+  readonly satisfied: readonly SatisfiedProjectManifestExtension[];
+  /** Manifest pins whose package is absent from installed state. */
+  readonly missing: readonly ExactExtensionSpec[];
+  /** Manifest pins whose package is installed at a different version. */
+  readonly mismatched: readonly MismatchedProjectManifestExtension[];
+}
+/**
+ * Extracts the package name from an npm specifier, stripping any version suffix.
+ * Handles both scoped (`@scope/pkg@ver`) and unscoped (`pkg@ver`) packages.
+ * Returns the full string unchanged if no version separator is found.
+ * @param spec - npm package specifier (e.g. `@makaio/extension-workflow@0.1.4` or `@makaio/extension-workflow`)
+ * @returns The package name without version
+ */
+declare function extractNpmPackageName(spec: string): string;
+/**
+ * Parse and validate an extension spec string as an exact semantic version reference.
+ *
+ * Version ranges (e.g. `^1.0.0`, `~1.0.0`) are rejected because the project manifest
+ * must pin extensions to reproducible, auditable versions.
+ * @param spec - An npm-style package-at-version string, e.g. `@makaio/extension-workflow@0.1.4`.
+ * @returns Parsed {@link ExactExtensionSpec} with the package name, version, and original spec.
+ * @throws If the spec does not contain an `@`-separated exact semantic version.
+ */
+declare function parseExactExtensionSpec(spec: string): ExactExtensionSpec;
+/**
+ * Format an npm package name and exact version as a project manifest extension spec.
+ * @param packageName - npm package name without a version suffix.
+ * @param version - Exact semantic version.
+ * @returns A validated `package@version` manifest spec.
+ */
+declare function formatExactExtensionSpec(packageName: string, version: string): string;
+/**
+ * Compare exact project manifest extension pins with installed singleton state.
+ * @param manifestSpecs - Exact extension specs from `.makaio/manifest.json`.
+ * @param installedExtensions - Installed extension package versions.
+ * @returns Satisfied, missing, and version-mismatched manifest entries.
+ */
+declare function compareProjectManifestExtensions(manifestSpecs: readonly string[], installedExtensions: readonly InstalledExtensionVersion[]): ProjectManifestExtensionDiff;
+/**
+ * Zod schema for the project manifest.
+ *
+ * Uses `.passthrough()` to preserve host-owned namespace keys that are outside
+ * the framework's knowledge (e.g. `hosts`, custom tooling keys).
+ */
+declare const ProjectManifestSchema: z.ZodObject<{
+  $schema: z.ZodOptional<z.ZodString>;
+  extensions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$loose>;
+/** Shape of a validated project manifest, including passthrough host-owned keys. */
+type ProjectManifest = z.infer<typeof ProjectManifestSchema>;
+/**
+ * Walk upward from `startDir` looking for a Makaio project manifest, stopping at the git root.
+ *
+ * The search terminates at the first directory containing a `.git` entry; if no manifest is
+ * found by that point, `null` is returned.
+ * @param startDir - Absolute path to the directory where the upward search begins.
+ * @returns Absolute path to the manifest file, or `null` if none was found.
+ */
+declare function findProjectManifestPath(startDir: string): Promise<string | null>;
+/**
+ * Read and validate a project manifest from disk.
+ * @param manifestPath - Absolute path to the manifest JSON file.
+ * @returns Validated {@link ProjectManifest}.
+ * @throws If the file cannot be read or the content fails schema validation.
+ */
+declare function readProjectManifest(manifestPath: string): Promise<ProjectManifest>;
+/**
+ * Write a project manifest to disk as pretty-printed JSON.
+ *
+ * The write is performed atomically via a temporary file and rename to avoid
+ * partial reads by concurrent processes.
+ * @param manifestPath - Absolute path where the manifest should be written.
+ * @param manifest - Manifest data to serialise and persist.
+ */
+declare function writeProjectManifest(manifestPath: string, manifest: ProjectManifest): Promise<void>;
+/**
+ * Checks whether a filesystem path exists.
+ * @param candidate - Path to check
+ * @returns true if the path exists and is accessible
+ */
+declare function pathExists(candidate: string): Promise<boolean>;
+//#endregion
+export { ExactExtensionSpec, InstalledExtensionVersion, MismatchedProjectManifestExtension, PROJECT_MANIFEST_BASENAME, PROJECT_MANIFEST_FILE, PROJECT_MANIFEST_SCHEMA_ID, ProjectManifest, ProjectManifestExtensionDiff, ProjectManifestSchema, SatisfiedProjectManifestExtension, compareProjectManifestExtensions, extractNpmPackageName, findProjectManifestPath, formatExactExtensionSpec, parseExactExtensionSpec, pathExists, readProjectManifest, writeProjectManifest };

package/dist/utils/project-manifest.mjs

@@ -0,0 +1 @@
+import{MAKAIO_PROJECT_DIR as e}from"./scope-paths.mjs";import{z as t}from"zod";import n from"node:fs/promises";import r from"node:path";import{randomUUID as i}from"node:crypto";const a=`manifest.json`,o=r.join(e,a),s=`makaio/project-manifest/v1`,c=/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/u,l=/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/u;function u(e){if(e.startsWith(`@`)){let t=e.indexOf(`@`,1);return t===-1?e:e.slice(0,t)}let t=e.indexOf(`@`);return t===-1?e:e.slice(0,t)}function d(e){let t=u(e),n=t.length<e.length?e.slice(t.length+1):``;if(t.length===0||n.length===0)throw Error(`Project manifest extension specs must include an exact version: ${e}`);if(!l.test(t)||t.length>214)throw Error(`Project manifest extension specs must use npm package names: ${e}`);if(!c.test(n))throw Error(`Project manifest extension specs must use exact semantic versions: ${e}`);return{packageName:t,version:n,spec:e}}function f(e,t){return d(`${e}@${t}`).spec}function p(e,t){let n=new Map(t.map(e=>[e.name,e.version])),r=[],i=[],a=[];for(let t of e){let e=d(t),o=n.get(e.packageName);o===void 0?i.push(e):o===e.version?r.push({manifest:e,installedVersion:o}):a.push({manifest:e,installedVersion:o})}return{satisfied:r,missing:i,mismatched:a}}const m=t.string().superRefine((e,t)=>{try{d(e)}catch(e){t.addIssue({code:`custom`,message:e instanceof Error?e.message:String(e)})}}),h=t.object({$schema:t.string().optional(),extensions:t.array(m).default([])}).passthrough();async function g(e){let t=r.resolve(e);for(;;){let e=r.join(t,o),[n,i]=await Promise.all([y(e),y(r.join(t,`.git`))]);if(n)return e;if(i)return null;let a=r.dirname(t);if(a===t)return null;t=a}}async function _(e){let t=await n.readFile(e,`utf-8`);return h.parse(JSON.parse(t))}async function v(e,t){let a=h.parse(t);await n.mkdir(r.dirname(e),{recursive:!0});let o=`${e}.${process.pid}.${Date.now()}.${i()}.tmp`;await n.writeFile(o,`${JSON.stringify(a,null,2)}\n`,`utf-8`);try{await n.rename(o,e)}catch(e){throw await n.unlink(o).catch(()=>void 0),e}}async function y(e){try{return await n.access(e),!0}catch{return!1}}export{a as PROJECT_MANIFEST_BASENAME,o as PROJECT_MANIFEST_FILE,s as PROJECT_MANIFEST_SCHEMA_ID,h as ProjectManifestSchema,p as compareProjectManifestExtensions,u as extractNpmPackageName,g as findProjectManifestPath,f as formatExactExtensionSpec,d as parseExactExtensionSpec,y as pathExists,_ as readProjectManifest,v as writeProjectManifest};

package/dist/utils/resolve-package-root.d.mts

@@ -0,0 +1,12 @@
+//#region packages/utils/src/resolve-package-root.d.ts
+/**
+ * Resolve a server-side package root from an ESM import meta object.
+ *
+ * Browser imports intentionally return `undefined` so package declarations can
+ * be evaluated by UI bundles without resolving filesystem paths.
+ * @param importMeta - Module import metadata from the package entrypoint.
+ * @returns Parent directory of the package entrypoint, or `undefined` in browser/non-file contexts.
+ */
+declare function resolvePackageRoot(importMeta: Pick<ImportMeta, 'url'>): string | undefined;
+//#endregion
+export { resolvePackageRoot };

package/dist/utils/resolve-package-root.mjs

@@ -0,0 +1 @@
+import{fileURLToPath as e}from"node:url";function t(t){return globalThis.window===void 0&&t.url.startsWith(`file:`)?e(new URL(`..`,t.url)):void 0}export{t as resolvePackageRoot};

package/dist/utils/scope-paths.d.mts

@@ -0,0 +1,33 @@
+//#region packages/utils/src/scope-paths.d.ts
+/** Directory name for project-scoped Makaio configuration and assets. */
+declare const MAKAIO_PROJECT_DIR = ".makaio";
+/** Portable relative path for personal, untracked project-local Makaio assets. */
+declare const MAKAIO_PERSONAL_DIR = ".makaio/personal";
+/** Scope layer identifier for resolved Makaio asset paths. */
+type ScopePathLayer = 'global' | 'project' | 'personal';
+/** Resolved asset directory for a single scope layer. */
+interface ResolvedScopePath {
+  /** Scope layer this path represents. */
+  readonly layer: ScopePathLayer;
+  /** Resolved filesystem path to the asset directory. */
+  readonly path: string;
+}
+interface ResolveScopePathsOptions {
+  /** Asset subdirectory name, for example `workflows`, `skills`, or `config`. */
+  readonly asset: string;
+  /** Resolved Makaio home directory. */
+  readonly makaioHome: string;
+  /** Active repository root path, when a project is open. */
+  readonly repoPath?: string;
+}
+/**
+ * Resolve layered Makaio asset paths from broadest to narrowest precedence.
+ *
+ * The function performs no filesystem I/O. Returned directories may or may not
+ * exist; callers own discovery, parsing, merge, and watch behavior.
+ * @param options - Asset name and scope roots to resolve.
+ * @returns Ordered scope-layer paths.
+ */
+declare function resolveScopePaths(options: ResolveScopePathsOptions): ResolvedScopePath[];
+//#endregion
+export { MAKAIO_PERSONAL_DIR, MAKAIO_PROJECT_DIR, ResolveScopePathsOptions, ResolvedScopePath, ScopePathLayer, resolveScopePaths };

package/dist/utils/scope-paths.mjs

@@ -0,0 +1 @@
+import e from"node:path";const t=`.makaio`,n=`${t}/personal`;function r(r){i(r.asset);let a=[{layer:`global`,path:e.join(r.makaioHome,r.asset)}];return r.repoPath!==void 0&&a.push({layer:`project`,path:e.join(r.repoPath,t,r.asset)},{layer:`personal`,path:e.join(r.repoPath,n,r.asset)}),a}function i(t){if(!(t.length>0&&t!==`.`&&t!==`..`&&!e.isAbsolute(t)&&!/[\\/]/u.test(t)))throw Error(`Scope path asset must be a single relative directory name. Received: "${t}"`)}export{n as MAKAIO_PERSONAL_DIR,t as MAKAIO_PROJECT_DIR,r as resolveScopePaths};

package/dist/utils/workspace-packages.d.mts

@@ -0,0 +1,59 @@
+//#region packages/utils/src/workspace-packages.d.ts
+/** Workspace glob entries normalized for package.json scanning. */
+interface WorkspaceGlobResolution {
+  /** Positive workspace package descriptor patterns. */
+  readonly patterns: readonly string[];
+  /** Negative workspace patterns normalized for package descriptor matching. */
+  readonly ignore: readonly string[];
+}
+/** Options for workspace package descriptor discovery. */
+interface DiscoverWorkspacePackageOptions {
+  /** Workspace globs to use instead of reading the root package.json. */
+  readonly patterns?: readonly string[];
+}
+/**
+ * Read package-manager workspace globs from a parsed package.json object.
+ *
+ * Supports both Yarn's array shape and npm/pnpm's `{ packages: [...] }` shape.
+ * Invalid entries are ignored so callers can decide whether an empty result is
+ * acceptable in their context.
+ * @param packageJson - Parsed root package.json value.
+ * @returns Workspace glob entries in declaration order.
+ */
+declare function parseWorkspaceGlobs(packageJson: unknown): readonly string[];
+/**
+ * Read workspace globs from the root package.json in `workspaceRoot`.
+ * @param workspaceRoot - Absolute workspace root directory.
+ * @returns Workspace glob entries in declaration order.
+ */
+declare function readWorkspaceGlobs(workspaceRoot: string): Promise<readonly string[]>;
+/**
+ * Convert workspace globs into package.json match patterns and ignore patterns.
+ *
+ * Package-manager workspaces describe package directories. Repository scanners
+ * in this codebase need package descriptors, so positive entries get
+ * `/package.json` appended while negated directory entries become ignore globs.
+ * @param workspaces - Raw workspace globs from a root package.json.
+ * @returns Positive descriptor patterns plus normalized ignores.
+ */
+declare function resolveWorkspacePackageJsonGlobs(workspaces: readonly string[]): WorkspaceGlobResolution;
+/**
+ * Discover package.json files declared by workspace globs.
+ * @param workspaceRoot - Absolute workspace root directory.
+ * @param options - Optional discovery overrides.
+ * @returns Absolute package.json paths.
+ */
+declare function discoverWorkspacePackageJsonPaths(workspaceRoot: string, options?: DiscoverWorkspacePackageOptions): Promise<readonly string[]>;
+/**
+ * Discover workspace packages as a package-name to directory index.
+ *
+ * Malformed or unnamed package descriptors are skipped; callers that need
+ * schema-specific validation should read the returned descriptor paths
+ * directly via {@link discoverWorkspacePackageJsonPaths}.
+ * @param workspaceRoot - Absolute workspace root directory.
+ * @param options - Optional discovery overrides.
+ * @returns Package-name to absolute package directory map.
+ */
+declare function discoverWorkspacePackageIndex(workspaceRoot: string, options?: DiscoverWorkspacePackageOptions): Promise<ReadonlyMap<string, string>>;
+//#endregion
+export { DiscoverWorkspacePackageOptions, WorkspaceGlobResolution, discoverWorkspacePackageIndex, discoverWorkspacePackageJsonPaths, parseWorkspaceGlobs, readWorkspaceGlobs, resolveWorkspacePackageJsonGlobs };

package/dist/utils/workspace-packages.mjs

@@ -0,0 +1 @@
+import*as e from"node:fs/promises";import t from"node:path";import{glob as n}from"glob";function r(e){if(typeof e!=`object`||!e||Array.isArray(e))return[];let t=e.workspaces,n=Array.isArray(t)?t:c(t)?t.packages:void 0;return Array.isArray(n)?n.filter(e=>typeof e==`string`):[]}async function i(n){let i=t.join(n,`package.json`);return r(JSON.parse(await e.readFile(i,`utf-8`)))}function a(e){let t=[],n=[];for(let r of e)if(r.startsWith(`!`)){let e=r.slice(1);n.push(`${e}/**`)}else t.push(`${r}/package.json`);return{patterns:t,ignore:n}}async function o(e,t={}){let{patterns:r,ignore:o}=a(t.patterns??await i(e));return r.length===0?[]:(await n([...r],{cwd:e,absolute:!0,ignore:[...o,`**/node_modules/**`]})).sort()}async function s(e,n={}){let r=await o(e,n),i=new Map;for(let e of r){let n=(await l(e))?.name;typeof n==`string`&&n.length>0&&i.set(n,t.dirname(e))}return i}function c(e){return typeof e==`object`&&!!e&&!Array.isArray(e)&&`packages`in e}async function l(t){try{let n=JSON.parse(await e.readFile(t,`utf-8`));if(typeof n==`object`&&n&&!Array.isArray(n))return n}catch{}}export{s as discoverWorkspacePackageIndex,o as discoverWorkspacePackageJsonPaths,r as parseWorkspaceGlobs,i as readWorkspaceGlobs,a as resolveWorkspacePackageJsonGlobs};

package/dist/utils/workspace-root.d.mts

@@ -0,0 +1,24 @@
+//#region packages/utils/src/workspace-root.d.ts
+/**
+ * Resolve the workspace root from a package directory 2-4 levels below the root.
+ *
+ * Supports two source layouts:
+ * - **Prefixed source layout**: workspace root contains `framework/package.json`;
+ *   the workspace root is the nearest ancestor (up to 4 levels) that contains
+ *   `framework/package.json`.
+ * - **Package-root layout**: workspace root contains `package.json` directly;
+ *   the workspace root is the nearest ancestor that contains `package.json`.
+ *
+ * Resolution walks bounded candidate depths from shallowest to deepest. A
+ * package root named `framework` is treated as nested source layout only when
+ * its parent also has a package manifest and contains that directory as a
+ * workspace marker; other package roots win immediately so checkouts embedded
+ * in another workspace do not overshoot.
+ * @param packageDir - Absolute path to a package directory inside the repo
+ *   (e.g. the value of `path.dirname(fileURLToPath(import.meta.url))`).
+ * @returns Absolute path to the workspace root.
+ * @throws If neither supported source layout is detected at any candidate depth.
+ */
+declare function resolveWorkspaceRoot(packageDir: string): string;
+//#endregion
+export { resolveWorkspaceRoot };

package/dist/utils/workspace-root.mjs

@@ -0,0 +1,2 @@
+import e from"node:path";import{existsSync as t}from"node:fs";function n(n){if(!e.isAbsolute(n))throw Error(`[workspace-root] packageDir must be absolute. Received: "${n}"`);let r=[e.resolve(n,`../..`),e.resolve(n,`../../..`),e.resolve(n,`../../../..`)];for(let n of r)if(t(e.join(n,`package.json`))){let r=e.dirname(n);return e.basename(n)===`framework`&&t(e.join(r,`package.json`))&&t(e.join(r,`framework`,`package.json`))?r:n}throw Error(`[workspace-root] Could not resolve workspace root from "${n}". Checked:\n${r.map(e=>`- ${e}`).join(`
+`)}`)}export{n as resolveWorkspaceRoot};

package/dist/variant-CT6XBP6T.mjs

@@ -0,0 +1 @@
+import{z as e}from"zod";import{createBusNamespace as t}from"@makaio/framework/core";const n=e.enum([`base`,`cef`]),r=e.enum([`downloading`,`progress`,`applying`,`complete`,`error`]),i={getInfo:{request:e.object({}),response:e.object({variant:n,bundleCEF:e.boolean(),defaultRenderer:e.enum([`native`,`cef`])})},requestUpgrade:{request:e.object({targetVariant:n}),response:e.union([e.object({accepted:e.literal(!0),downloadSizeBytes:e.number().int().nonnegative().optional(),message:e.string().optional()}),e.object({accepted:e.literal(!1),message:e.string().min(1)})])},upgradeProgress:e.object({status:r,percent:e.number().min(0).max(100).optional(),message:e.string().optional()})},a=t(`host:variant`,i),o=a.subjects;export{r as a,i,o as n,n as r,a as t};