@lotagate/cli 0.1.24 → 0.1.26

package/dist/infrastructure/extensions/plugin-agent-discovery.js

@@ -0,0 +1 @@
+import c from"node:fs/promises";import u from"node:path";import{parsePluginAgentDocument as f}from"../../domain/extensions/plugin-agent-manifest.js";import{CliError as p}from"../../domain/errors/cli-error.js";import{CLI_ERROR_CODES as g}from"../../domain/errors/error-codes.js";import{isFileNotFound as d}from"../filesystem/fs-errors.js";import{readFileBounded as h}from"../filesystem/bounded-file-reader.js";import{RESOURCE_LIMITS as y}from"../../domain/runtime/resource-limits.js";class C{async discover(r){let a;try{a=await c.readdir(r,{withFileTypes:!0})}catch(t){if(d(t))return[];throw t}const s=[];for(const t of a.filter(e=>e.isFile()&&e.name.endsWith(".yaml")).sort((e,n)=>e.name.localeCompare(n.name))){const e=t.name.slice(0,-5);if(!/^[a-z0-9][a-z0-9-]{0,63}$/u.test(e))throw i(`Invalid plugin agent file name: ${t.name}`);const n=u.join(r,t.name);if((await c.lstat(n)).isSymbolicLink())throw i(`Plugin agent must not be a symbolic link: ${t.name}`);const m=await h(n,y.skillDocumentBytes);if(m.truncated)throw i(`Plugin agent exceeds the supported size: ${t.name}`);const l=f(m.bytes.toString("utf8"),r);if(l.name!==e)throw i(`Plugin agent name must match its file name: ${t.name}`);s.push(l)}return s}}function i(o){return new p(g.PLUGIN_MANIFEST_INVALID,o,{category:"extension",userMessage:`Invalid plugin agent: ${o}`})}export{C as PluginAgentDiscovery};

package/dist/infrastructure/extensions/plugin-discovery.d.ts

@@ -0,0 +1,5 @@
+import { type PluginManifest } from '../../domain/extensions/plugin-manifest.js';
+export declare class PluginDiscovery {
+    discover(roots: readonly string[]): Promise<readonly PluginManifest[]>;
+}
+export declare function validatePluginManifest(manifest: PluginManifest): Promise<void>;

package/dist/infrastructure/extensions/plugin-discovery.js

@@ -0,0 +1 @@
+import s from"node:fs/promises";import a from"node:path";import{parsePluginManifest as y,PLUGIN_LAYOUT as o}from"../../domain/extensions/plugin-manifest.js";import{CliError as c}from"../../domain/errors/cli-error.js";import{CLI_ERROR_CODES as l}from"../../domain/errors/error-codes.js";import{isFileNotFound as p}from"../filesystem/fs-errors.js";import{readJsonFileBounded as h}from"../filesystem/bounded-json-reader.js";import{RESOURCE_LIMITS as w}from"../../domain/runtime/resource-limits.js";import{listExtensionDirectories as d}from"./extension-directory-reader.js";class k{async discover(t){const i=[];for(const e of t)for(const r of await d(e)){const f=a.join(r,o.markerDirectory,o.manifestFile);try{const u=y(await h(f,w.pluginManifestBytes),r);await L(u),i.push(u)}catch(u){if(!p(u))throw u;if(await I(r))throw P()}}return i.sort((e,r)=>e.name.localeCompare(r.name))}}async function I(n){try{return await s.stat(a.join(n,".codex-plugin","plugin.json")),!0}catch(t){if(p(t))return!1;throw t}}function P(){return new c(l.PLUGIN_MANIFEST_INVALID,"Only the .lotagate-plugin/plugin.json plugin format is supported.",{category:"extension",userMessage:"This plugin uses an unsupported format. Reinstall it using the LotaGate plugin structure."})}async function L(n){const t=await s.realpath(n.directory);await D(t,o.skillsDirectory),await m(t,o.readmeFile),await m(t,o.licenseFile);for(const i of[o.markerDirectory,o.skillsDirectory,o.agentsDirectory,o.hooksDirectory,o.mcpDirectory]){const e=a.resolve(t,i);if(e!==t&&!e.startsWith(`${t}${a.sep}`))throw g(i);try{if((await s.lstat(e)).isSymbolicLink())throw g(i);const f=await s.realpath(e);if(f!==t&&!f.startsWith(`${t}${a.sep}`))throw g(i)}catch(r){if(r instanceof c)throw r;if(p(r))continue;throw new c(l.PLUGIN_MANIFEST_INVALID,`Plugin path is not contained in the plugin directory: ${i}`,{category:"extension",userMessage:"Plugin contains an unsafe path.",cause:r})}}}async function D(n,t){try{const i=await s.lstat(a.join(n,t));if(!i.isDirectory()||i.isSymbolicLink())throw new Error("invalid-directory")}catch(i){throw new c(l.PLUGIN_MANIFEST_INVALID,`Plugin directory is missing or invalid: ${t}`,{category:"extension",userMessage:`Plugin must contain the ${t}/ directory.`,cause:i})}}async function m(n,t){try{const i=await s.lstat(a.join(n,t));if(!i.isFile()||i.isSymbolicLink())throw new Error("invalid-file")}catch(i){throw new c(l.PLUGIN_MANIFEST_INVALID,`Plugin file is missing or invalid: ${t}`,{category:"extension",userMessage:`Plugin must contain ${t}.`,cause:i})}}function g(n){return new c(l.PLUGIN_MANIFEST_INVALID,`Plugin path is not contained in the plugin directory: ${n}`,{category:"extension",userMessage:"Plugin contains an unsafe path."})}export{k as PluginDiscovery,L as validatePluginManifest};

package/dist/infrastructure/extensions/plugin-manager.d.ts

@@ -0,0 +1,23 @@
+import { type ExtensionIntegrityOptions } from './extension-integrity.js';
+import { type PluginManifest } from '../../domain/extensions/plugin-manifest.js';
+export interface InstalledPlugin {
+    manifest: PluginManifest;
+    enabled: boolean;
+    integrity?: string;
+}
+export type PluginInstallOptions = ExtensionIntegrityOptions;
+export interface PluginListOptions {
+    verifyIntegrity?: boolean;
+}
+export declare class PluginManager {
+    private readonly root;
+    private readonly statePath;
+    constructor(root: string);
+    list(roots?: readonly string[], options?: PluginListOptions): Promise<readonly InstalledPlugin[]>;
+    install(source: string, options?: PluginInstallOptions): Promise<InstalledPlugin>;
+    uninstall(name: string): Promise<boolean>;
+    setEnabled(name: string, enabled: boolean): Promise<void>;
+    private readState;
+    private writeState;
+}
+export declare function hashDirectory(directory: string): Promise<string>;

package/dist/infrastructure/extensions/plugin-manager.js

@@ -0,0 +1,2 @@
+import g from"node:crypto";import{verifyExtensionIntegrity as M}from"./extension-integrity.js";import c from"node:fs/promises";import o from"node:path";import{parsePluginManifest as b,PLUGIN_LAYOUT as d}from"../../domain/extensions/plugin-manifest.js";import{CliError as P}from"../../domain/errors/cli-error.js";import{CLI_ERROR_CODES as j}from"../../domain/errors/error-codes.js";import{PluginDiscovery as x,validatePluginManifest as I}from"./plugin-discovery.js";import{atomicWriteFile as D,replaceDirectoryWithRollback as N,withFileLock as y}from"../filesystem/atomic-file-store.js";import{isFileNotFound as S}from"../filesystem/fs-errors.js";import{readJsonFileBounded as E}from"../filesystem/bounded-json-reader.js";import{RESOURCE_LIMITS as v}from"../../domain/runtime/resource-limits.js";import{parseExtensionState as U}from"../../domain/extensions/extension-state.js";import{MAX_PLUGIN_DEPTH as T,MAX_PLUGIN_FILE_BYTES as k,MAX_PLUGIN_FILES as A,MAX_PLUGIN_TOTAL_BYTES as O}from"./extensions-constants.js";class Q{root;statePath;constructor(t){this.root=t,this.statePath=o.join(t,"state.json")}async list(t=[this.root],a={}){const i=await this.readState(),e=await new x().discover(t),r=[];for(const s of e){const f=a.verifyIntegrity===!1?void 0:await p(s.directory);r.push({manifest:s,enabled:i[s.name]?.enabled!==!1,...f===void 0?{}:{integrity:f}})}return r}async install(t,a={}){const i=o.resolve(t),e=o.join(i,d.markerDirectory,d.manifestFile);let r;try{r=await E(e,v.pluginManifestBytes)}catch(h){if(S(h)){const F=o.join(i,".codex-plugin","plugin.json");try{throw await c.stat(F),l("Only the .lotagate-plugin/plugin.json format is supported.")}catch(w){if(w instanceof P)throw w}}throw l("Plugin source must contain .lotagate-plugin/plugin.json.")}const s=b(r,i);await I(s);const f=await p(i);M(f,a,l),await c.mkdir(this.root,{recursive:!0});const m=o.join(this.root,L(s.name)),u=`${m}.tmp-${g.randomUUID()}`;return y(`${m}.install`,async()=>{try{await c.cp(i,u,{recursive:!0,force:!1,errorOnExist:!0}),await I({...s,directory:u});const h=await p(u);if(h!==f)throw l("Plugin changed while it was being installed.");return await N(u,m),await this.setEnabled(s.name,!0),{manifest:{...s,directory:m},enabled:!0,integrity:h}}finally{await c.rm(u,{recursive:!0,force:!0})}})}async uninstall(t){const a=o.join(this.root,L(t));return y(`${a}.install`,async()=>{const i=(await this.list([this.root],{verifyIntegrity:!1})).find(e=>e.manifest.name===t);return i===void 0?!1:(await c.rm(i.manifest.directory,{recursive:!0,force:!0}),await y(this.statePath,async()=>{const e=await this.readState();delete e[t],await this.writeState(e)}),!0)})}async setEnabled(t,a){await y(this.statePath,async()=>{const i=await this.readState();i[t]={enabled:a},await this.writeState(i)})}async readState(){try{return U(await E(this.statePath,v.workspaceSettingsBytes))}catch(t){if(S(t))return{};throw t}}async writeState(t){await D(this.statePath,`${JSON.stringify(t,null,2)}
+`)}}async function p(n){const t=g.createHash("sha256");let a=0;for(const i of await _(n)){const e=o.relative(n,i).split(o.sep).join("/"),r=await c.stat(i);if(r.size>k)throw l("Plugin file exceeds the integrity scan limit.");if(a+=r.size,a>O)throw l("Plugin exceeds the total integrity scan limit.");t.update(e),t.update("\0"),t.update(await c.readFile(i)),t.update("\0")}return t.digest("hex")}async function _(n,t=0,a={files:0}){if(t>T)throw l("Plugin directory nesting exceeds the integrity scan limit.");const i=[];for(const e of(await c.readdir(n,{withFileTypes:!0})).sort((r,s)=>r.name.localeCompare(s.name))){const r=o.join(n,e.name);if(e.isSymbolicLink())throw l("Plugin packages must not contain symbolic links.");if(e.isDirectory())i.push(...await _(r,t+1,a));else if(e.isFile()&&(i.push(r),a.files+=1,a.files>A))throw l("Plugin contains too many files for the integrity scan.")}return i}function L(n){return`plugin-${Buffer.from(n,"utf8").toString("base64url")}`}function l(n){return new P(j.PLUGIN_MANIFEST_INVALID,n,{category:"extension",userMessage:`Unable to install plugin: ${n}`})}export{Q as PluginManager,p as hashDirectory};

package/dist/infrastructure/extensions/skill-discovery.d.ts

@@ -0,0 +1,4 @@
+import { type SkillManifest } from '../../domain/extensions/skill-manifest.js';
+export declare class SkillDiscovery {
+    discover(roots: readonly string[]): Promise<readonly SkillManifest[]>;
+}

package/dist/infrastructure/extensions/skill-discovery.js

@@ -0,0 +1 @@
+import m from"node:path";import{parseSkillDocument as c}from"../../domain/extensions/skill-manifest.js";import{CliError as a}from"../../domain/errors/cli-error.js";import{CLI_ERROR_CODES as f}from"../../domain/errors/error-codes.js";import{isFileNotFound as p}from"../filesystem/fs-errors.js";import{readFileBounded as u}from"../filesystem/bounded-file-reader.js";import{RESOURCE_LIMITS as d}from"../../domain/runtime/resource-limits.js";import{listExtensionDirectories as S}from"./extension-directory-reader.js";class _{async discover(s){const i=new Map;for(const e of s)for(const t of await S(e)){const l=m.join(t,"SKILL.md");try{const o=await u(l,d.skillDocumentBytes);if(o.truncated)continue;const n=c(o.bytes.toString("utf8"),t);i.has(n.name)||i.set(n.name,n)}catch(o){if(!p(o)&&!I(o))throw o}}return[...i.values()].sort((e,t)=>e.name.localeCompare(t.name))}}function I(r){return r instanceof a&&r.code===f.SKILL_FRONTMATTER_INVALID}export{_ as SkillDiscovery};

package/dist/infrastructure/extensions/skill-installer.d.ts

@@ -0,0 +1,9 @@
+import { type ExtensionIntegrityOptions } from './extension-integrity.js';
+import { type SkillManifest } from '../../domain/extensions/skill-manifest.js';
+export interface InstalledSkill {
+    manifest: SkillManifest;
+    integrity: string;
+}
+export declare class SkillInstaller {
+    install(source: string, root: string, options?: ExtensionIntegrityOptions): Promise<InstalledSkill | undefined>;
+}

package/dist/infrastructure/extensions/skill-installer.js

@@ -0,0 +1 @@
+import n from"node:fs/promises";import{verifyExtensionIntegrity as w}from"./extension-integrity.js";import h from"node:crypto";import o from"node:path";import{parseSkillDocument as S}from"../../domain/extensions/skill-manifest.js";import{CliError as k}from"../../domain/errors/cli-error.js";import{CLI_ERROR_CODES as I}from"../../domain/errors/error-codes.js";import{hashDirectory as p}from"./plugin-manager.js";import{isFileNotFound as c}from"../filesystem/fs-errors.js";import{readFileBounded as g}from"../filesystem/bounded-file-reader.js";import{RESOURCE_LIMITS as L}from"../../domain/runtime/resource-limits.js";import{replaceDirectoryWithRollback as D,withFileLock as F}from"../filesystem/atomic-file-store.js";class N{async install(e,a,r={}){if(await E(e))return;const i=await v(o.resolve(e));if(i===void 0)return;const m=await g(o.join(i,"SKILL.md"),L.skillDocumentBytes);if(m.truncated)throw f("Skill document exceeds the supported size.");const u=S(m.bytes.toString("utf8"),i),d=await p(i);w(d,r,f),await n.mkdir(a,{recursive:!0});const s=o.join(a,u.name),l=`${s}.tmp-${h.randomUUID()}`;return F(`${s}.install`,async()=>{try{await n.cp(i,l,{recursive:!0,force:!1,errorOnExist:!0});const y=await p(l);if(y!==d)throw new Error("Skill changed while it was being installed.");return await D(l,s),{manifest:{...u,directory:s},integrity:y}}finally{await n.rm(l,{recursive:!0,force:!0})}})}}async function E(t){try{return(await n.stat(o.join(t,".lotagate-plugin","plugin.json"))).isFile()}catch(e){if(!c(e))throw e;return!1}}async function v(t){try{if((await n.stat(o.join(t,"SKILL.md"))).isFile())return t}catch(r){if(!c(r))throw r}let e;try{e=await n.readdir(t,{withFileTypes:!0})}catch(r){if(c(r))return;throw r}const a=[];for(const r of e.filter(i=>i.isDirectory()))try{(await n.stat(o.join(t,r.name,"SKILL.md"))).isFile()&&a.push(o.join(t,r.name))}catch(i){if(!c(i))throw i}if(a.length>1)throw f("Source contains multiple skills. Pass the individual skill directory.");return a[0]}function f(t){return new k(I.SKILL_FRONTMATTER_INVALID,t,{category:"extension",userMessage:`Unable to install skill: ${t}`})}export{N as SkillInstaller};

package/dist/infrastructure/extensions/skill-manager.d.ts

@@ -0,0 +1,22 @@
+import type { SkillManifest } from '../../domain/extensions/skill-manifest.js';
+import type { SkillRootScope } from './skill-roots.js';
+export type ScopedSkill = SkillManifest & {
+    skillKey: string;
+    enabled: boolean;
+    scope: SkillRootScope['scope'];
+    root: string;
+    statePath: string;
+    pluginName?: string;
+};
+export interface ScopedSkillListOptions {
+    includeShadowed?: boolean;
+}
+export declare class SkillManager {
+    private readonly statePath;
+    constructor(statePath: string);
+    listScoped(scopes: readonly SkillRootScope[], options?: ScopedSkillListOptions): Promise<readonly ScopedSkill[]>;
+    setEnabled(name: string, enabled: boolean, statePath?: string): Promise<void>;
+    remove(name: string, root: string, statePath?: string): Promise<boolean>;
+    private readState;
+    private writeState;
+}

package/dist/infrastructure/extensions/skill-manager.js

@@ -0,0 +1,2 @@
+import p from"node:fs/promises";import{SkillDiscovery as d}from"./skill-discovery.js";import{atomicWriteFile as f,withFileLock as u}from"../filesystem/atomic-file-store.js";import{isFileNotFound as w}from"../filesystem/fs-errors.js";import{readJsonFileBounded as S}from"../filesystem/bounded-json-reader.js";import{RESOURCE_LIMITS as y}from"../../domain/runtime/resource-limits.js";import{parseExtensionState as g}from"../../domain/extensions/extension-state.js";class M{statePath;constructor(e){this.statePath=e}async listScoped(e,s={}){const a=new Map,i=[],n=new Set,c=new Set;for(const t of e){a.has(t.statePath)||a.set(t.statePath,await this.readState(t.statePath));const m=a.get(t.statePath);for(const o of await new d().discover([t.root])){const r=t.scope==="plugin",h=n.has(o.name)||!r&&t.scope==="builtin"&&c.has(o.name);if(s.includeShadowed!==!0&&h)continue;r?c.add(o.name):t.scope!=="builtin"&&n.add(o.name);const l=r?`${t.pluginName??"plugin"}:${o.name}`:o.name;i.push({...o,skillKey:l,enabled:m[l]?.enabled!==!1,scope:t.scope,root:t.root,statePath:t.statePath,...t.pluginName===void 0?{}:{pluginName:t.pluginName}})}}return i}async setEnabled(e,s,a=this.statePath){await u(a,async()=>{const i=await this.readState(a);i[e]={enabled:s},await this.writeState(i,a)})}async remove(e,s,a=this.statePath){const i=(await new d().discover([s])).find(n=>n.name===e||`${n.name}`===e);return i===void 0?!1:(await p.rm(i.directory,{recursive:!0,force:!0}),await u(a,async()=>{const n=await this.readState(a);delete n[e],await this.writeState(n,a)}),!0)}async readState(e=this.statePath){try{return g(await S(e,y.workspaceSettingsBytes))}catch(s){if(w(s))return{};throw s}}async writeState(e,s=this.statePath){await f(s,`${JSON.stringify(e,null,2)}
+`)}}export{M as SkillManager};

package/dist/infrastructure/extensions/skill-roots.d.ts

@@ -0,0 +1,19 @@
+import type { ExtensionScope } from '../../domain/extensions/extension-scope.js';
+export interface SkillRootScope {
+    scope: ExtensionScope | 'plugin' | 'builtin';
+    root: string;
+    statePath: string;
+    pluginName?: string;
+}
+export interface PluginSkillRoot {
+    root: string;
+    pluginName: string;
+}
+/**
+ * Returns skill roots in precedence order: project, user, enabled plugins,
+ * then immutable package-provided skills. SkillManager keeps project/user
+ * definitions authoritative while qualifying plugin identities so independent
+ * plugins can expose the same raw skill name safely.
+ */
+export declare function resolveSkillRootScopes(cwd: string, globalConfigDir: string, pluginSkillRoots?: readonly PluginSkillRoot[]): readonly SkillRootScope[];
+export declare function builtinSkillsDirectory(executablePath?: string): string;

package/dist/infrastructure/extensions/skill-roots.js

@@ -0,0 +1 @@
+import t from"node:path";import{existsSync as a}from"node:fs";import{fileURLToPath as p}from"node:url";function h(s,o,i=[]){const r=t.join(s,".lotagate","skills"),e=t.join(o,"skills-state.json");return[{scope:"project",root:r,statePath:t.join(s,".lotagate","skills-state.json")},{scope:"user",root:t.join(o,"skills"),statePath:e},...i.map(({root:l,pluginName:n})=>({scope:"plugin",root:l,pluginName:n,statePath:e})),{scope:"builtin",root:c(),statePath:e}]}function c(s=process.execPath){const o=t.resolve(t.dirname(s),"..","skills");return a(o)?o:p(new URL("../../../skills/",import.meta.url))}export{c as builtinSkillsDirectory,h as resolveSkillRootScopes};

package/dist/infrastructure/extensions/skill-tool-executor.d.ts

@@ -0,0 +1,20 @@
+import type { ToolDefinition } from '@lotagate/sdk';
+import type { ToolExecutionContext, ToolExecutor, ToolInfo, ToolResult } from '@lotagate/agent-sdk';
+import type { SkillManifest } from '../../domain/extensions/skill-manifest.js';
+import type { SkillScopeStore } from '../../application/extensions/skill-scope-store.js';
+import type { Logger } from '../../ports/logger.js';
+/** Exposes the same skill capability definitions to runtime and context accounting. */
+export declare function skillToolDefinitions(): readonly ToolDefinition[];
+/** Presents validated, model-invocable skills as lazy agent tools. */
+export declare class SkillToolExecutor implements ToolExecutor {
+    private readonly scopes;
+    private readonly logger?;
+    private readonly skills;
+    constructor(skills: readonly (SkillManifest & {
+        enabled: boolean;
+        skillKey?: string;
+    })[], scopes: SkillScopeStore, logger?: Logger | undefined);
+    listTools(): readonly ToolDefinition[];
+    getToolInfo(toolName: string): ToolInfo | undefined;
+    execute(toolName: string, input: Record<string, unknown>, context: ToolExecutionContext): Promise<ToolResult>;
+}

package/dist/infrastructure/extensions/skill-tool-executor.js

@@ -0,0 +1,2 @@
+import{withToolExecutionLogging as f}from"../observability/tool-execution-logger.js";const a=[u("skill.list","List enabled skills available to the agent.",{type:"object",properties:{},additionalProperties:!1}),u("skill.load","Load instructions for one enabled skill by name when its description matches the task.",{type:"object",properties:{name:{type:"string",description:"Enabled skill name."}},required:["name"],additionalProperties:!1})];function d(){return a}class g{scopes;logger;skills;constructor(e,i,r){this.scopes=i,this.logger=r,this.skills=e.filter(n=>n.enabled&&n.modelInvocable)}listTools(){return d()}getToolInfo(e){return a.some(i=>k(i)===e)?{toolName:e,source:"custom",executorId:"skill-catalog",metadata:{category:"skill",risk:"read"}}:void 0}async execute(e,i,r){return f(this.logger,{toolName:e,source:"custom",context:r,details:{skillName:typeof i.name=="string"?i.name:void 0}},async()=>{if(e==="skill.list")return c(JSON.stringify(this.skills.map(s=>({name:s.skillKey??s.name,description:s.description}))));if(e!=="skill.load")return l(`Unknown skill tool: ${e}`);const n=i.name;if(typeof n!="string")return l("skill.load requires a skill name.");const o=this.skills.find(s=>(s.skillKey??s.name)===n);return o===void 0?l(`Skill is unavailable: ${n}`):(this.scopes.activate(r.runId,o),c(m(o.body,r.maxResultBytes)))})}}function u(t,e,i){return{type:"function",function:{name:t,description:e,parameters:i}}}function k(t){return"function"in t?t.function.name:void 0}function c(t){return{content:t,isError:!1}}function l(t){return{content:t,isError:!0}}function m(t,e){const i=Buffer.from(t,"utf8");return i.byteLength<=e?t:`${i.subarray(0,e).toString("utf8")}
+[truncated]`}export{g as SkillToolExecutor,d as skillToolDefinitions};

package/dist/infrastructure/filesystem/atomic-file-store.d.ts

@@ -0,0 +1,28 @@
+import fs from 'node:fs/promises';
+export type AdvisoryLockProcessStartCache = Map<number, {
+    checkedAt: number;
+    startTimeMs?: number;
+}>;
+/** Writes a file through a same-directory temporary file and rename. */
+export declare function atomicWriteFile(filePath: string, data: string | Uint8Array, mode?: number): Promise<void>;
+/** Replaces a directory under an advisory lock with rollback if the commit fails. */
+export declare function replaceDirectoryWithRollback(temporary: string, destination: string): Promise<void>;
+/** Creates an advisory lock and removes it again when lock metadata cannot be persisted. */
+export declare function acquireAdvisoryFileLock(lockPath: string): Promise<fs.FileHandle>;
+/** Handles Windows reporting an existing, exclusively opened lock as EPERM/EACCES. */
+export declare function isAdvisoryLockContention(error: unknown, lockPath: string): Promise<boolean>;
+/** Closes an advisory lock handle and removes its lock file even when close fails. */
+export declare function releaseAdvisoryFileLock(handle: fs.FileHandle, lockPath: string): Promise<void>;
+/** Serializes mutations across CLI processes using an advisory lock file. */
+export declare function withFileLock<T>(filePath: string, operation: () => Promise<T>, options?: {
+    timeoutMs?: number;
+    staleMs?: number;
+    userMessage?: string;
+}): Promise<T>;
+/** Acquires a cross-process advisory lock and returns its async release function. */
+export declare function acquireFileLock(filePath: string, options?: {
+    timeoutMs?: number;
+    staleMs?: number;
+    userMessage?: string;
+}): Promise<() => Promise<void>>;
+export declare function recoverStaleAdvisoryLock(lockPath: string, staleMs: number, processStartTimes?: AdvisoryLockProcessStartCache): Promise<boolean>;

package/dist/infrastructure/filesystem/atomic-file-store.js

@@ -0,0 +1 @@
+import m from"node:crypto";import a from"node:fs/promises";import p from"node:path";import{CliError as M}from"../../domain/errors/cli-error.js";import{CLI_ERROR_CODES as S}from"../../domain/errors/error-codes.js";import{isAlreadyExists as T,isFileNotFound as u}from"./fs-errors.js";import{currentProcessStartTimeMs as E,readProcessStartTimeMs as h}from"../platform/process-identity.js";import{DEFAULT_LOCK_STALE_MS as A,DEFAULT_LOCK_TIMEOUT_MS as _,LOCK_RETRY_MS as C,PROCESS_START_TIME_CACHE_MS as L,PROCESS_START_TIME_TOLERANCE_MS as g}from"./filesystem-constants.js";async function J(e,r,t=384){await a.mkdir(p.dirname(e),{recursive:!0});const i=`${e}.tmp-${process.pid}-${m.randomUUID()}`;try{await a.writeFile(i,r,{mode:t}),await a.rename(i,e)}finally{await a.rm(i,{force:!0})}}async function W(e,r){const t=`${r}.backup-${process.pid}-${m.randomUUID()}`;let i=!1,o=!1;try{try{await a.rename(r,t),i=!0}catch(n){if(!u(n))throw n}try{await a.rename(e,r)}catch(n){if(i)try{await a.rename(t,r)}catch(s){throw o=!0,new AggregateError([n,s],`Installation and recovery failed. Previous contents are preserved at ${t}.`)}throw n}}finally{o||await a.rm(t,{recursive:!0,force:!0})}}async function k(e){const r=await a.open(e,"wx",384);try{return await r.writeFile(JSON.stringify({pid:process.pid,processStartTimeMs:E(),createdAt:new Date().toISOString()})),r}catch(t){throw await l(r,e),t}}async function v(e,r){if(T(e))return!0;if(!w(e))return!1;try{return await a.stat(r),!0}catch(t){return u(t)||w(t)}}async function l(e,r){try{await e.close()}finally{await a.rm(r,{force:!0})}}async function B(e,r,t={}){const i=await O(e,t);try{return await r()}finally{await i()}}async function O(e,r={}){const t=`${e}.lock`,i=r.timeoutMs??_,o=r.staleMs??A;await a.mkdir(p.dirname(e),{recursive:!0});const n=Date.now()+i,s=new Map;let c;for(;c===void 0;)try{c=await k(t)}catch(d){if(!await v(d,t))throw d;if(await F(t,o,s))continue;if(Date.now()>=n)throw new M(S.CONFIG_LOCKED,`Configuration file is locked: ${e}`,{category:"config",userMessage:r.userMessage??"A configuration update is already in progress. Try again shortly.",retryable:!0});await new Promise(y=>setTimeout(y,C))}let f=!1;return async()=>{f||(f=!0,await l(c,t))}}function w(e){return typeof e=="object"&&e!==null&&"code"in e&&(e.code==="EPERM"||e.code==="EACCES")}async function F(e,r,t=new Map){let i;try{i=await a.stat(e)}catch(n){if(u(n))return!1;throw n}if(Date.now()-i.mtimeMs<r)return!1;let o={};try{o=R(JSON.parse(await a.readFile(e,"utf8")))}catch{}return o.pid!==void 0&&await b(o,t)?!1:(await a.rm(e,{force:!0}),!0)}function R(e){if(typeof e!="object"||e===null)return{};const r=e;return{...typeof r.pid=="number"&&Number.isSafeInteger(r.pid)&&r.pid>0?{pid:r.pid}:{},...typeof r.processStartTimeMs=="number"&&Number.isFinite(r.processStartTimeMs)?{processStartTimeMs:r.processStartTimeMs}:{}}}async function b(e,r){const t=e.pid;if(t===void 0||!x(t))return!1;if(e.processStartTimeMs===void 0)return!0;const i=await D(t,r);return i===void 0?!0:Math.abs(i-e.processStartTimeMs)<=g}async function D(e,r){const t=Date.now(),i=r.get(e);if(i!==void 0&&t-i.checkedAt<L)return i.startTimeMs;const o=await h(e);return r.set(e,{checkedAt:t,...o===void 0?{}:{startTimeMs:o}}),o}function x(e){if(e===process.pid)return!0;try{return process.kill(e,0),!0}catch(r){return r instanceof Error&&"code"in r&&r.code==="EPERM"}}export{k as acquireAdvisoryFileLock,O as acquireFileLock,J as atomicWriteFile,v as isAdvisoryLockContention,F as recoverStaleAdvisoryLock,l as releaseAdvisoryFileLock,W as replaceDirectoryWithRollback,B as withFileLock};

package/dist/infrastructure/filesystem/bounded-file-reader.d.ts

@@ -0,0 +1,6 @@
+export interface BoundedFileRead {
+    bytes: Buffer;
+    truncated: boolean;
+}
+/** Reads at most maxBytes and never loads an entire untrusted file into memory. */
+export declare function readFileBounded(filePath: string, maxBytes: number): Promise<BoundedFileRead>;

package/dist/infrastructure/filesystem/bounded-file-reader.js

@@ -0,0 +1 @@
+import i from"node:fs/promises";async function y(l,f){const t=Math.max(0,Math.floor(f)),r=await i.open(l,"r");try{const o=[];let a=0;const s=t+1;for(;a<s;){const e=Buffer.alloc(Math.min(65536,s-a)),{bytesRead:n}=await r.read(e,0,e.byteLength,null);if(n===0)break;o.push(e.subarray(0,n)),a+=n}const c=Buffer.concat(o);return{bytes:c.subarray(0,t),truncated:c.byteLength>t}}finally{await r.close()}}export{y as readFileBounded};

package/dist/infrastructure/filesystem/bounded-json-reader.d.ts

@@ -0,0 +1 @@
+export declare function readJsonFileBounded(filePath: string, maxBytes: number): Promise<unknown>;

package/dist/infrastructure/filesystem/bounded-json-reader.js

@@ -0,0 +1 @@
+import{readFileBounded as o}from"./bounded-file-reader.js";async function d(e,t){const r=await o(e,t);if(r.truncated)throw new Error(`File exceeds the maximum supported size: ${e}`);return JSON.parse(r.bytes.toString("utf8"))}export{d as readJsonFileBounded};

package/dist/infrastructure/filesystem/filesystem-constants.d.ts

@@ -0,0 +1,8 @@
+export declare const DEFAULT_LOCK_TIMEOUT_MS = 5000;
+export declare const DEFAULT_LOCK_STALE_MS: number;
+export declare const LOCK_RETRY_MS = 25;
+export declare const PROCESS_START_TIME_TOLERANCE_MS = 2000;
+export declare const PROCESS_START_TIME_CACHE_MS = 1000;
+export declare const FILE_DIFF_MAX_BYTES: number;
+export declare const FILE_DIFF_MAX_INPUT_LINES = 400;
+export declare const FILE_DIFF_MAX_LINES = 240;

package/dist/infrastructure/filesystem/filesystem-constants.js

@@ -0,0 +1 @@
+const _=5e3,E=9e5,o=25,t=2e3,S=1e3,T=65536,I=400,L=240;export{E as DEFAULT_LOCK_STALE_MS,_ as DEFAULT_LOCK_TIMEOUT_MS,T as FILE_DIFF_MAX_BYTES,I as FILE_DIFF_MAX_INPUT_LINES,L as FILE_DIFF_MAX_LINES,o as LOCK_RETRY_MS,S as PROCESS_START_TIME_CACHE_MS,t as PROCESS_START_TIME_TOLERANCE_MS};

package/dist/infrastructure/filesystem/fs-errors.d.ts

@@ -0,0 +1,2 @@
+export declare function isFileNotFound(error: unknown): boolean;
+export declare function isAlreadyExists(error: unknown): boolean;

package/dist/infrastructure/filesystem/fs-errors.js

@@ -0,0 +1 @@
+function n(t){return typeof t=="object"&&t!==null&&"code"in t&&t.code==="ENOENT"}function c(t){return typeof t=="object"&&t!==null&&"code"in t&&t.code==="EEXIST"}export{c as isAlreadyExists,n as isFileNotFound};

package/dist/infrastructure/filesystem/gateway-media-input-reader.d.ts

@@ -0,0 +1,12 @@
+export interface GatewayImageEditInput {
+    readonly images: readonly Uint8Array[];
+    readonly mask: Uint8Array | undefined;
+}
+export interface GatewayAudioInput {
+    readonly bytes: Uint8Array;
+    readonly filename: string;
+    readonly sourceName: string;
+}
+/** Reads local upload inputs sequentially and enforces the gateway's published limits. */
+export declare function readGatewayImageEditInput(imageValue: string, maskValue: string | undefined, cwd: string): Promise<GatewayImageEditInput>;
+export declare function readGatewayAudioInput(source: string, cwd: string): Promise<GatewayAudioInput>;

package/dist/infrastructure/filesystem/gateway-media-input-reader.js

@@ -0,0 +1 @@
+import p from"node:path";import{GATEWAY_MEDIA_LIMITS as n,validateImageEditInputCount as l,validateImageEditTotalSize as u,validateUploadSize as m}from"../../domain/media/gateway-media-contract.js";import{CliError as E}from"../../domain/errors/cli-error.js";import{CLI_ERROR_CODES as I}from"../../domain/errors/error-codes.js";import{normalizeImage as b}from"../clipboard/image-normalizer.js";import{readFileBounded as g}from"./bounded-file-reader.js";import{resolveExternalPath as y}from"./path-resolver.js";async function v(r,o,e){const t=r.split(",").map(a=>a.trim()).filter(Boolean);l(t);const s=[];let d=0;for(const a of t){const f=await c(a,e,n.imageEditFileBytes,"Image",["image/png","image/jpeg","image/webp"]);d+=f.byteLength,u(d),s.push(f)}const i=o===void 0?void 0:await c(o,e,n.imageEditMaskBytes,"Mask",["image/png"]);return i!==void 0&&u(d+i.byteLength),{images:s,mask:i}}async function M(r,o){const e=await y(r,{cwd:o}),t=await g(e,n.audioUploadBytes);return t.truncated&&m(n.audioUploadBytes+1,n.audioUploadBytes,"Audio file"),m(t.bytes.byteLength,n.audioUploadBytes,"Audio file"),{bytes:t.bytes,filename:p.basename(e),sourceName:p.parse(p.basename(e)).name}}async function c(r,o,e,t,s){const d=await y(r,{cwd:o}),i=await g(d,e);i.truncated&&m(e+1,e,t);const a=b(i.bytes,void 0,e);if(!s.includes(a.mimeType))throw new E(I.ATTACHMENT_FORMAT_UNSUPPORTED,`${t} format is not accepted by the gateway.`,{category:"media",userMessage:`${t} must use one of: ${s.join(", ")}.`});return m(a.bytes.byteLength,e,t),a.bytes}export{M as readGatewayAudioInput,v as readGatewayImageEditInput};

package/dist/infrastructure/filesystem/local-filesystem-tool-executor.d.ts

@@ -0,0 +1,25 @@
+import type { ToolDefinition } from '@lotagate/sdk';
+import type { ToolExecutionContext, ToolExecutor, ToolInfo, ToolResult } from '@lotagate/agent-sdk';
+import { type FileChangeDiff } from '../../domain/filesystem/file-change-diff.js';
+import type { ToolActivityObserver } from '../../ports/tool-activity.js';
+import type { Logger } from '../../ports/logger.js';
+/** Exposes the same filesystem capability definitions to runtime and context accounting. */
+export declare function filesystemToolDefinitions(): readonly ToolDefinition[];
+export declare function filesystemToolRisk(toolName: string): 'read' | 'write' | undefined;
+export declare class LocalFilesystemToolExecutor implements ToolExecutor {
+    private readonly options;
+    constructor(options?: {
+        onWrite?: (change: FileChangeDiff) => void | Promise<void>;
+        onActivity?: ToolActivityObserver;
+        writeScope?: readonly string[];
+        logger?: Logger;
+    });
+    listTools(): readonly ToolDefinition[];
+    getToolInfo(toolName: string): ToolInfo | undefined;
+    execute(toolName: string, input: Record<string, unknown>, context: ToolExecutionContext): Promise<ToolResult>;
+    private read;
+    private list;
+    private write;
+    private exists;
+}
+export declare function isWithinWriteScope(filePath: string, context: ToolExecutionContext, scopes: readonly string[]): Promise<boolean>;

package/dist/infrastructure/filesystem/local-filesystem-tool-executor.js

@@ -0,0 +1,3 @@
+import d from"node:fs/promises";import o from"node:path";import{createFileChangeDiff as g}from"../../domain/filesystem/file-change-diff.js";import{assertWorkspaceWriteTarget as h,resolveWorkspacePath as u}from"./path-resolver.js";import{readFileBounded as y}from"./bounded-file-reader.js";import{isFileNotFound as m}from"./fs-errors.js";import{atomicWriteFile as k}from"./atomic-file-store.js";import{formatFilesystemActivityName as F}from"../../application/agent/tool-display.js";import{FILE_DIFF_MAX_BYTES as T,FILE_DIFF_MAX_INPUT_LINES as b,FILE_DIFF_MAX_LINES as v}from"./filesystem-constants.js";import{withToolExecutionLogging as S}from"../observability/tool-execution-logger.js";const w=[p("filesystem.read","Read a UTF-8 text file inside the trusted workspace for inspection. Never reproduce detailed file contents in the final response unless the user explicitly requests them.",{path:{type:"string",description:"Workspace-relative file path."}},["path"]),p("filesystem.list","List entries inside a trusted workspace directory. Do not pass a file path to this tool. For inspecting or reading files, use filesystem.read instead.",{path:{type:"string",description:"Optional workspace-relative directory path. Defaults to the workspace root."}},[]),p("filesystem.write","Write UTF-8 text to a file inside the trusted workspace.",{path:{type:"string",description:"Workspace-relative file path."},content:{type:"string",description:"UTF-8 file content."}},["path","content"]),p("filesystem.exists","Check whether a workspace-relative path exists.",{path:{type:"string",description:"Workspace-relative path."}},["path"])];function E(){return w}function L(i){if(w.some(t=>W(t)===i))return i==="filesystem.write"?"write":"read"}class q{options;constructor(t={}){this.options=t}listTools(){return E()}getToolInfo(t){const e=L(t);return e===void 0?void 0:{toolName:t,source:"filesystem",executorId:"local-filesystem",metadata:{risk:e}}}async execute(t,e,r){return S(this.options.logger,{toolName:t,source:"filesystem",context:r,details:{path:typeof e.path=="string"?e.path:void 0}},async()=>{const s=this.options.onActivity?.start({key:`${r.runId}:${t}`,toolName:t,source:"filesystem",label:R(t,e.path)});let a;try{switch(t){case"filesystem.read":a=await this.read(e,r);break;case"filesystem.list":a=await this.list(e,r);break;case"filesystem.write":a=await this.write(e,r);break;case"filesystem.exists":a=await this.exists(e,r);break;default:a=l(`Unknown filesystem tool: ${t}`);break}}catch(n){a=l(n instanceof Error?n.message:String(n))}return s?.complete(a.isError===!0,a.metadata),a})}async read(t,e){const r=await u(t.path,e),s=await y(r,e.maxResultBytes);return c(`${s.bytes.toString("utf8")}${s.truncated?`
+[truncated]`:""}`)}async list(t,e){const r=await u(t.path===void 0||typeof t.path=="string"&&t.path.trim().length===0?".":t.path,e),s=[],a=Math.max(1,Math.floor(e.maxResultBytes/64)),n=await d.opendir(r);try{for(let f=await n.read();f!==null&&(s.push({name:f.name,kind:f.isDirectory()?"directory":"file"}),!(s.length>=a));f=await n.read());}finally{await n.close()}return c(_(Buffer.from(JSON.stringify(s)),e.maxResultBytes))}async write(t,e){if(typeof t.content!="string")return l("filesystem.write requires string content.");const r=await u(t.path,e,!0);if(this.options.writeScope!==void 0&&!await x(r,e,this.options.writeScope))return l("filesystem.write path is outside the delegated worker write scope.");const s=Buffer.from(t.content,"utf8");if(s.byteLength>e.maxResultBytes)return l("filesystem.write content exceeds the configured limit.");const a=await I(r);await d.mkdir(o.dirname(r),{recursive:!0}),await h(r,e),await k(r,s),await h(r,e);const n=g(String(t.path),a.content,t.content,{maxInputLines:b,maxLines:v,truncated:a.truncated});try{await this.options.onWrite?.(n)}catch{}return{...c(`Wrote ${s.byteLength} bytes.`),metadata:{fileChange:{path:n.path,additions:n.additions,deletions:n.deletions}}}}async exists(t,e){try{return await u(t.path,e),c("true")}catch(r){if(m(r))return c("false");throw r}}}async function x(i,t,e){const r=await d.realpath(o.resolve(t.workspaceRoot??t.cwd??process.cwd())),s=o.relative(r,o.resolve(i));return s.startsWith("..")||o.isAbsolute(s)?!1:e.some(a=>{const n=o.normalize(a).replace(/[\\/]$/u,"");return n==="."?!0:s===n||s.startsWith(`${n}${o.sep}`)})}async function I(i){try{const t=await y(i,T);return{content:t.bytes.toString("utf8"),truncated:t.truncated}}catch(t){return m(t)?{content:"",truncated:!1}:{content:"",truncated:!0}}}function p(i,t,e,r){return{type:"function",function:{name:i,description:t,parameters:{type:"object",properties:e,required:r,additionalProperties:!1}}}}function W(i){return"function"in i?i.function.name:void 0}function c(i){return{content:i,isError:!1}}function l(i){return{content:i,isError:!0}}function _(i,t){return i.byteLength<=t?i.toString("utf8"):`${i.subarray(0,t).toString("utf8")}
+[truncated]`}function R(i,t){return F(i,t)}export{q as LocalFilesystemToolExecutor,E as filesystemToolDefinitions,L as filesystemToolRisk,x as isWithinWriteScope};

package/dist/infrastructure/filesystem/path-resolver.d.ts

@@ -0,0 +1,20 @@
+export declare function resolveWorkspacePath(input: unknown, context: {
+    cwd?: string;
+    workspaceRoot?: string;
+}, allowMissing?: boolean): Promise<string>;
+/** Resolves an explicitly supplied local path without applying workspace containment. */
+export declare function resolveExternalPath(input: unknown, context: {
+    cwd?: string;
+}, allowMissing?: boolean): Promise<string>;
+/** Resolves an output path while refusing a final symlink target. */
+export declare function resolveExternalOutputPath(input: unknown, context: {
+    cwd?: string;
+}): Promise<string>;
+/** Revalidates a write target immediately at the filesystem mutation boundary. */
+export declare function assertWorkspaceWriteTarget(filePath: string, context: {
+    cwd?: string;
+    workspaceRoot?: string;
+}): Promise<void>;
+/** Revalidates an explicitly selected external output without following the final path component. */
+export declare function assertExternalWriteTarget(filePath: string): Promise<void>;
+export declare function assertInside(root: string, candidate: string): void;

package/dist/infrastructure/filesystem/path-resolver.js

@@ -0,0 +1 @@
+import n from"node:fs/promises";import s from"node:path";import{CliError as h}from"../../domain/errors/cli-error.js";import{CLI_ERROR_CODES as w}from"../../domain/errors/error-codes.js";import{isFileNotFound as l}from"./fs-errors.js";async function A(t,e,o=!1){if(typeof t!="string"||t.trim().length===0)throw new h(w.TOOL_ARGUMENT_INVALID,"A relative workspace path is required.",{category:"tool",userMessage:"The filesystem tool requires a non-empty path."});const a=await n.realpath(s.resolve(e.workspaceRoot??e.cwd??process.cwd())),r=await n.realpath(s.resolve(e.cwd??a));p(a,r);const i=s.resolve(r,t);try{const c=await n.realpath(i);return p(a,c),c}catch(c){if(!o||!l(c))throw c;return y(i,a)}}async function m(t,e,o=!1){const a=d(t,e.cwd);try{return await n.realpath(a)}catch(r){if(!o||!l(r))throw r;return u(a)}}async function M(t,e){const o=d(t,e.cwd),a=await m(s.dirname(o),e,!0),r=s.join(a,s.basename(o));return await f(r),r}async function y(t,e){return u(t,e)}async function u(t,e){const o=[];let a=t;for(;;)try{const r=await n.realpath(a);return e!==void 0&&p(e,r),s.join(r,...o)}catch(r){if(!l(r))throw r;const i=s.dirname(a);if(i===a)throw r;o.unshift(s.basename(a)),a=i}}function d(t,e=process.cwd()){if(typeof t!="string"||t.trim().length===0)throw new h(w.INVALID_ARGUMENT,"A non-empty local path is required.",{category:"path",userMessage:"A non-empty local path is required."});return s.resolve(e,t)}async function f(t){try{if((await n.lstat(t)).isSymbolicLink())throw new h(w.INVALID_ARGUMENT,"Output paths cannot be symbolic links.",{category:"path",userMessage:"The output path cannot be a symbolic link."})}catch(e){if(!l(e))throw e}}async function T(t,e){const o=await n.realpath(s.resolve(e.workspaceRoot??e.cwd??process.cwd())),a=await n.realpath(s.dirname(t));p(o,a);try{const r=await n.realpath(t);p(o,r)}catch(r){if(!l(r))throw r}}async function I(t){await n.realpath(s.dirname(t)),await f(t)}function p(t,e){const o=s.relative(t,e);if(o===".."||o.startsWith(`..${s.sep}`)||s.isAbsolute(o))throw new h(w.PROJECT_SYMLINK_ESCAPE,"Path escapes the trusted workspace.",{category:"project",userMessage:"Tool access was denied because the path is outside the trusted workspace."})}export{I as assertExternalWriteTarget,p as assertInside,T as assertWorkspaceWriteTarget,M as resolveExternalOutputPath,m as resolveExternalPath,A as resolveWorkspacePath};

package/dist/infrastructure/filesystem/workspace-media-artifact-store.d.ts

@@ -0,0 +1,13 @@
+import type { MediaArtifactRequest, StoredMediaArtifact } from '../../domain/media/media-contract.js';
+import type { Logger } from '../../ports/logger.js';
+/** Persists generated media below the workspace by default or in an explicitly supplied local directory. */
+export declare class WorkspaceMediaArtifactStore {
+    private readonly cwd;
+    private readonly logger?;
+    constructor(cwd: string, logger?: Logger | undefined);
+    writeMany(request: MediaArtifactRequest, artifacts: readonly Uint8Array[]): Promise<readonly StoredMediaArtifact[]>;
+    private resolveDirectory;
+    private resolveTarget;
+    private resolveOutputPath;
+    private context;
+}

package/dist/infrastructure/filesystem/workspace-media-artifact-store.js

@@ -0,0 +1 @@
+import h from"node:fs/promises";import a from"node:path";import{CliError as T}from"../../domain/errors/cli-error.js";import{CLI_ERROR_CODES as v}from"../../domain/errors/error-codes.js";import{atomicWriteFile as x}from"./atomic-file-store.js";import{assertExternalWriteTarget as E,assertWorkspaceWriteTarget as D,resolveExternalOutputPath as $,resolveExternalPath as A,resolveWorkspacePath as m}from"./path-resolver.js";const P=1e4,k={image:a.join("tmp","images"),speech:a.join("tmp","speechs"),transcription:a.join("tmp","transcribes"),translation:a.join("tmp","translates"),video:a.join("tmp","videos")};class L{cwd;logger;constructor(t,r){this.cwd=t,this.logger=r}async writeMany(t,r){if(r.length===0)throw l("The provider returned no media artifacts.");if(t.out!==void 0&&r.length!==1)throw l("--out can only be used when exactly one artifact is returned. Use --out-dir instead.");const o=await this.resolveDirectory(t),i=t.outDir!==void 0,n=[];for(const[s,d]of r.entries()){const w=await this.resolveTarget(t,o,s,r.length),p=t.out===void 0,c=p?await _(w,this.context(),i):w;let f=p;try{await h.mkdir(a.dirname(c),{recursive:!0}),await u(c,this.context(),i),f||(f=await O(c,t.force,this.context(),i)),await x(c,d),await u(c,this.context(),i)}catch(y){throw f&&await b(c,this.context(),i),y}n.push({path:c,bytes:d.byteLength})}return this.logger?.info("Media artifacts stored.",{kind:t.kind,artifactCount:n.length,artifactBytes:n.reduce((s,d)=>s+d.bytes,0)}),n}async resolveDirectory(t){const r=t.outDir??k[t.kind];return t.outDir===void 0?m(r,this.context(),!0):A(r,{cwd:this.cwd},!0)}async resolveTarget(t,r,o,i){if(t.out!==void 0){R(t.out);const d=i>1?`-${o+1}`:"";return this.resolveOutputPath(a.join(r,`${t.out}${d}.${t.extension}`),t.outDir!==void 0)}const n=i>1?`-${o+1}`:"",s=a.join(r,`${j(t.source)}${n}.${t.extension}`);return this.resolveOutputPath(s,t.outDir!==void 0)}resolveOutputPath(t,r){return r?$(t,{cwd:this.cwd}):m(t,this.context(),!0)}context(){return{cwd:this.cwd,workspaceRoot:this.cwd}}}async function u(e,t,r){r?await E(e):await D(e,t)}async function O(e,t,r,o){if(t)return!1;try{return await h.mkdir(a.dirname(e),{recursive:!0}),await u(e,r,o),await(await h.open(e,"wx",384)).close(),await u(e,r,o),!0}catch(i){throw g(i)?l(`Refusing to overwrite an existing file: ${e}. Use --force with --out to replace it.`):i}}async function _(e,t,r){const o=a.parse(e);for(let i=0;i<P;i+=1){const n=i===0?e:a.join(o.dir,`${o.name}-${i+1}${o.ext}`);try{return await h.mkdir(o.dir,{recursive:!0}),await u(n,t,r),await(await h.open(n,"wx",384)).close(),await u(n,t,r),n}catch(s){if(!g(s))throw s}}throw l(`Unable to allocate a unique output path near: ${e}.`)}async function b(e,t,r){try{await u(e,t,r),await h.rm(e,{force:!0})}catch{}}function j(e){const t=e.normalize("NFKD").replace(/[^a-zA-Z0-9]+/gu,"-").replace(/^-+|-+$/gu,"").toLowerCase().slice(0,72);return t.length===0?"media":t}function R(e){const t=[...e].some(r=>{const o=r.codePointAt(0)??0;return o<32||o===127});if(e.length===0||e==="."||e===".."||e.includes("/")||e.includes("\\")||t)throw l("--out must be a filename without path separators or control characters.")}function g(e){return typeof e=="object"&&e!==null&&"code"in e&&e.code==="EEXIST"}function l(e){return new T(v.INVALID_ARGUMENT,e,{category:"media",userMessage:e})}export{L as WorkspaceMediaArtifactStore};

package/dist/infrastructure/logging/daily-rotating-file-writer.d.ts

@@ -0,0 +1,26 @@
+export interface DailyRotatingFileWriterOptions {
+    retentionDays: number;
+    now?: () => number;
+}
+export declare class DailyRotatingFileWriter {
+    private readonly directory;
+    private readonly options;
+    private readonly now;
+    private queue;
+    private queueBytes;
+    private dropped;
+    private drainPromise;
+    private closed;
+    private lastPrunedDate;
+    private lastError;
+    constructor(directory: string, options: DailyRotatingFileWriterOptions);
+    get health(): Readonly<{
+        dropped: number;
+        lastError?: Error;
+    }>;
+    write(line: string): void;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+    private drain;
+    private pruneAsync;
+}

package/dist/infrastructure/logging/daily-rotating-file-writer.js

@@ -0,0 +1,2 @@
+import f from"node:fs";import a from"node:fs/promises";import u from"node:path";import{RESOURCE_LIMITS as c}from"../../domain/runtime/resource-limits.js";class g{directory;options;now;queue=[];queueBytes=0;dropped=0;drainPromise=Promise.resolve();closed=!1;lastPrunedDate;lastError;constructor(t,r){this.directory=t,this.options=r,this.now=r.now??Date.now;try{f.mkdirSync(t,{recursive:!0,mode:448})}catch{}this.lastPrunedDate=""}get health(){return{dropped:this.dropped,...this.lastError===void 0?{}:{lastError:this.lastError}}}write(t){if(this.closed)return;const r=Buffer.byteLength(t,"utf8");if(this.queue.length>=c.logQueueEntries||this.queueBytes+r>c.logQueueBytes){this.dropped+=1;return}this.queue.push({filePath:u.join(this.directory,`lotagate-${h(this.now())}.jsonl`),line:t}),this.queueBytes+=r,this.drainPromise=this.drainPromise.then(()=>this.drain()).catch(i=>{this.lastError=i instanceof Error?i:new Error(String(i))})}async flush(){await this.drainPromise,this.queue.length>0&&(this.drainPromise=this.drainPromise.then(()=>this.drain()).catch(t=>{this.lastError=t instanceof Error?t:new Error(String(t))}),await this.drainPromise)}async close(){this.closed=!0,await this.flush()}async drain(){const t=h(this.now());if(t!==this.lastPrunedDate&&await this.pruneAsync()&&(this.lastPrunedDate=t),this.queue.length===0)return;const r=this.queue.splice(0,this.queue.length);this.queueBytes=0;const i=this.dropped;i>0&&r.push({filePath:u.join(this.directory,`lotagate-${h(this.now())}.jsonl`),line:`${JSON.stringify({timestamp:new Date(this.now()).toISOString(),level:"warn",message:"Log entries dropped because the file writer queue was full.",dropped:i})}
+`});const s=new Map;for(const e of r)s.set(e.filePath,[...s.get(e.filePath)??[],e.line]);try{for(const[e,n]of s)await a.appendFile(e,n.join(""),{encoding:"utf8",mode:384});this.dropped=0,this.lastError=void 0}catch(e){const n=[...r.filter(o=>!o.line.includes("Log entries dropped because the file writer queue was full.")),...this.queue];throw this.queue=n,this.queueBytes=n.reduce((o,d)=>o+Buffer.byteLength(d.line,"utf8"),0),this.lastError=e instanceof Error?e:new Error(String(e)),e}}async pruneAsync(){const t=this.now()-this.options.retentionDays*24*60*60*1e3;let r=!0;try{const i=await a.readdir(this.directory,{withFileTypes:!0});for(const s of i){if(!s.isFile())continue;const e=/^lotagate-(\d{4}-\d{2}-\d{2})\.jsonl$/u.exec(s.name);if(e===null||e[1]===void 0)continue;const n=Date.parse(`${e[1]}T00:00:00.000Z`);if(Number.isFinite(n)&&n<t)try{await a.rm(u.join(this.directory,s.name),{force:!0})}catch(o){r=!1,this.lastError=o instanceof Error?o:new Error(String(o))}}}catch(i){r=!1,this.lastError=i instanceof Error?i:new Error(String(i))}return r}}function h(l){return new Date(l).toISOString().slice(0,10)}export{g as DailyRotatingFileWriter};

package/dist/infrastructure/logging/log-redactor.d.ts

@@ -0,0 +1,2 @@
+export declare function redactLogDetails(details: Record<string, unknown> | undefined): Record<string, unknown> | undefined;
+export declare function redactLogText(value: string): string;

package/dist/infrastructure/logging/log-redactor.js

@@ -0,0 +1 @@
+import{SENSITIVE_KEY as f}from"./logging-constants.js";const E=32,u=4.2,a=/[A-Za-z0-9+/_=-]{32,}/gu;function d(t){if(t!==void 0)return s(t)}function s(t){return Object.fromEntries(Object.entries(t).map(([r,e])=>[r,f.test(r)?"[REDACTED]":p(e)]))}function p(t){return typeof t=="string"?o(t):Array.isArray(t)?t.map(r=>r!==null&&typeof r=="object"?s(r):typeof r=="string"?o(r):r):t!==null&&typeof t=="object"?s(t):t}function A(t){return o(t)}function o(t){return t.replace(/Bearer\s+[^\s]+/giu,"Bearer [REDACTED]").replace(/sk-[A-Za-z0-9_-]{8,}/gu,"[REDACTED]").replace(/((?:api[_-]?key|password|secret|token|authorization)\s*[:=]\s*)[^\s,]+/giu,"$1[REDACTED]").replace(/([?&][^=&#\s]*(?:key|token|secret|password|auth)[^=&#\s]*=)[^&#\s]+/giu,"$1[REDACTED]").replace(a,e=>T(e)?"[REDACTED]":e)}function T(t){return t.length<E||/\s/u.test(t)?!1:/^[0-9a-f]+$/iu.test(t)?i(t)>=3.5:i(t)>=u&&D(t)}function D(t){let r=0;return/[a-z]/u.test(t)&&(r+=1),/[A-Z]/u.test(t)&&(r+=1),/[0-9]/u.test(t)&&(r+=1),/[+/_=-]/u.test(t)&&(r+=1),r>=2}function i(t){const r=new Map;for(const n of t)r.set(n,(r.get(n)??0)+1);let e=0;for(const n of r.values()){const c=n/t.length;e-=c*Math.log2(c)}return e}export{d as redactLogDetails,A as redactLogText};

package/dist/infrastructure/logging/logging-constants.d.ts

@@ -0,0 +1,3 @@
+import type { LogLevel } from '../../ports/logger.js';
+export declare const SENSITIVE_KEY: RegExp;
+export declare const LEVEL_PRIORITY: Record<LogLevel, number>;

package/dist/infrastructure/logging/logging-constants.js

@@ -0,0 +1 @@
+const e=/(api.?key|authorization|credential|password|private.?key|secret|token)/iu,r={error:0,warn:1,info:2,debug:3,trace:4};export{r as LEVEL_PRIORITY,e as SENSITIVE_KEY};

package/dist/infrastructure/logging/logging-policy.d.ts

@@ -0,0 +1,6 @@
+import type { LogLevel } from '../../ports/logger.js';
+export interface LoggingPolicy {
+    level: LogLevel;
+    retentionDays: number;
+}
+export declare function resolveLoggingPolicy(env?: Readonly<Record<string, string | undefined>>): LoggingPolicy;

package/dist/infrastructure/logging/logging-policy.js

@@ -0,0 +1 @@
+import{readBoundedEnvironmentInteger as o}from"../config/environment-values.js";function L(r=process.env){const e=r.LOTAGATE_LOG_LEVEL?.trim().toLowerCase();return{level:e==="error"||e==="warn"||e==="debug"||e==="trace"?e:"info",retentionDays:o(r.LOTAGATE_LOG_RETENTION_DAYS,14,1,365)}}export{L as resolveLoggingPolicy};

package/dist/infrastructure/logging/structured-logger.d.ts

@@ -0,0 +1,24 @@
+import type { Logger, LogLevel } from '../../ports/logger.js';
+import type { Writable } from 'node:stream';
+import type { DailyRotatingFileWriter } from './daily-rotating-file-writer.js';
+export interface StructuredLoggerOptions {
+    level?: LogLevel;
+    consoleLevel?: LogLevel | 'none';
+    json?: boolean;
+    output?: Writable;
+    file?: DailyRotatingFileWriter;
+}
+export declare class StructuredLogger implements Logger {
+    private readonly minimumPriority;
+    private readonly consoleMinimumPriority;
+    private readonly output;
+    private readonly json;
+    private readonly file;
+    constructor(options?: StructuredLoggerOptions);
+    error(message: string, details?: Record<string, unknown>): void;
+    warn(message: string, details?: Record<string, unknown>): void;
+    info(message: string, details?: Record<string, unknown>): void;
+    debug(message: string, details?: Record<string, unknown>): void;
+    trace(message: string, details?: Record<string, unknown>): void;
+    private write;
+}

package/dist/infrastructure/logging/structured-logger.js

@@ -0,0 +1,4 @@
+import{redactLogDetails as m,redactLogText as u}from"./log-redactor.js";import{LEVEL_PRIORITY as r}from"./logging-constants.js";class h{minimumPriority;consoleMinimumPriority;output;json;file;constructor(i={}){this.minimumPriority=r[i.level??"info"],this.consoleMinimumPriority=i.consoleLevel==="none"?-1:r[i.consoleLevel??i.level??"info"],this.output=i.output??process.stderr,this.json=i.json??!1,this.file=i.file}error(i,t){this.write("error",i,t)}warn(i,t){this.write("warn",i,t)}info(i,t){this.write("info",i,t)}debug(i,t){this.write("debug",i,t)}trace(i,t){this.write("trace",i,t)}write(i,t,o){if(r[i]>this.minimumPriority)return;const n=m(o),e=u(t),s={timestamp:new Date().toISOString(),level:i,message:e,...n??{}};r[i]<=this.consoleMinimumPriority&&this.output.write(this.json?`${JSON.stringify(s)}
+`:`[${i}] ${e}
+`);try{this.file?.write(`${JSON.stringify(s)}
+`)}catch{}}}export{h as StructuredLogger};

package/dist/infrastructure/memory/file-memory-store.d.ts

@@ -0,0 +1,37 @@
+import type { MemoryBundle, MemoryDraft, MemoryRecord } from '../../domain/memory/memory.js';
+import { type MemorySearchHit, type MemorySearchQuery, type MemorySemanticHit } from '../../domain/memory/memory-search.js';
+import type { MemoryListOptions, MemoryStore } from '../../ports/memory-store.js';
+import type { PlatformPaths } from '../platform/platform-paths.js';
+import type { Logger } from '../../ports/logger.js';
+/** Local project memory. Journal writes are authoritative; index reads are the fast path. */
+export declare class FileMemoryStore implements MemoryStore {
+    private readonly paths;
+    private readonly logger?;
+    constructor(paths: PlatformPaths, logger?: Logger | undefined);
+    list(cwd: string, options?: MemoryListOptions): Promise<readonly MemoryRecord[]>;
+    search(cwd: string, query: MemorySearchQuery): Promise<readonly MemorySearchHit[]>;
+    ensureSemanticIndex(cwd: string, model: string, embed: (texts: readonly string[], signal?: AbortSignal) => Promise<readonly number[][]>, signal?: AbortSignal): Promise<void>;
+    semanticSearch(cwd: string, model: string, vector: readonly number[], maximum: number): Promise<readonly MemorySemanticHit[]>;
+    get(cwd: string, id: string): Promise<MemoryRecord | undefined>;
+    consolidate(cwd: string, draft: MemoryDraft): Promise<{
+        record: MemoryRecord;
+        action: 'insert' | 'merge' | 'supersede' | 'ignore';
+    }>;
+    forget(cwd: string, id: string): Promise<boolean>;
+    clear(cwd: string): Promise<number>;
+    markRetrieved(cwd: string, ids: readonly string[]): Promise<void>;
+    export(cwd: string): Promise<MemoryBundle>;
+    import(cwd: string, bundle: MemoryBundle): Promise<{
+        imported: number;
+        skipped: number;
+    }>;
+    private resolvePaths;
+    private readRecords;
+    private readSearchIndex;
+    private readIndex;
+    private readJournal;
+    private append;
+    private replaceJournal;
+    private writeIndex;
+    private pruneSemanticIndex;
+}

package/dist/infrastructure/memory/file-memory-store.js

@@ -0,0 +1,11 @@
+import V from"node:crypto";import j from"node:fs/promises";import S from"node:path";import{effectiveMemoryRecord as M,MEMORY_SCHEMA_VERSION as m,memoryRecordFromDraft as L,normalizeMemoryBundle as D,normalizeMemoryRecord as B}from"../../domain/memory/memory.js";import{buildMemorySearchIndex as z,isMemoryRetrievable as K,searchMemoryIndex as _}from"../../domain/memory/memory-search.js";import{memoryKindDefinition as U,MEMORY_KINDS as T}from"../../domain/memory/memory-kinds.js";import{RESOURCE_LIMITS as h}from"../../domain/runtime/resource-limits.js";import{atomicWriteFile as E,withFileLock as y}from"../filesystem/atomic-file-store.js";import{readJsonFileBounded as k}from"../filesystem/bounded-json-reader.js";import{isFileNotFound as O}from"../filesystem/fs-errors.js";import{createProjectKey as W}from"../sessions/project-session-paths.js";class pe{paths;logger;constructor(e,t){this.paths=e,this.logger=t}async list(e,t={}){return(await this.readRecords(this.resolvePaths(e))).map(i=>M(i)).filter(i=>t.kind===void 0||i.kind===t.kind).filter(i=>t.state===void 0||i.state===t.state).sort((i,n)=>n.updatedAt.localeCompare(i.updatedAt)||i.id.localeCompare(n.id))}async search(e,t){const r=this.resolvePaths(e),i=await this.readRecords(r),n=Object.fromEntries(i.map(a=>[a.id,M(a)])),o=await this.readSearchIndex(r,i);return _(n,o,t)}async ensureSemanticIndex(e,t,r,i){const n=this.resolvePaths(e),o=await this.readRecords(n),a=await J(n.semanticIndexFile),p=a?.model===t?a.entries:{},c=o.filter(d=>p[d.id]?.contentHash!==f(d));if(c.length===0)return;const l=await r(c.map(d=>`${d.statement}
+${d.rationale??""}
+${d.topics.join(" ")}`),i);if(l.length!==c.length)throw new Error("Embedding provider returned an unexpected number of vectors.");await y(n.journalFile,async()=>{const d=await this.readRecords(n,!0),g=await J(n.semanticIndexFile),v=g?.model===t?{...g.entries}:{};for(const[u,x]of c.entries()){const R=d.find(H=>H.id===x.id),F=l[u];R===void 0||F===void 0||f(R)!==f(x)||(P(F),v[x.id]={contentHash:f(x),vector:[...F]})}const A={schemaVersion:m,model:t,entries:v,updatedAt:I()},b=`${JSON.stringify(A)}
+`;if(Buffer.byteLength(b,"utf8")>h.memoryIndexBytes)throw new Error("Memory semantic index exceeds the supported size limit.");await E(n.semanticIndexFile,b)},w())}async semanticSearch(e,t,r,i){if(i<=0)return[];P(r);const n=this.resolvePaths(e);return y(n.journalFile,async()=>{const o=await this.readRecords(n,!0),a=await J(n.semanticIndexFile);if(a?.model!==t)return[];const p=new Map(o.map(c=>[c.id,M(c)]));return Object.keys(a.entries).flatMap(c=>{const l=a.entries[c];if(l===void 0)return[];const d=p.get(c);return d===void 0||!K(d)?[]:[{record:d,similarity:G(r,l.vector),rank:0}]}).sort((c,l)=>l.similarity-c.similarity||c.record.id.localeCompare(l.record.id)).slice(0,i).map((c,l)=>({...c,rank:l+1}))},w())}async get(e,t){const r=this.resolvePaths(e);return(await this.readRecords(r)).map(n=>M(n)).find(n=>n.id===t)}async consolidate(e,t){const r=this.resolvePaths(e);return y(r.journalFile,async()=>{const i=I(),n=L(V.randomUUID(),t,i),o=await this.readRecords(r,!0),a=o.find(u=>f(u)===f(n));if(a!==void 0){const u={...a,...n.rationale===void 0&&a.rationale===void 0?{}:{rationale:n.rationale??a.rationale},topics:[...new Set([...a.topics,...n.topics])].sort(),evidenceRefs:[...new Set([...a.evidenceRefs,...n.evidenceRefs])],updatedAt:i};if(!(JSON.stringify(u)!==JSON.stringify(a)))return{record:a,action:"ignore"};const R=o.map(F=>F.id===a.id?u:F);return await this.append(r,[{schemaVersion:m,type:"upsert",record:u}]),await this.writeIndex(r,R),{record:u,action:"merge"}}const p=new Set(n.supersedes),c=o.filter(u=>u.state==="active"&&p.has(u.id)),l=o.find(u=>u.state==="active"&&u.kind===n.kind&&ee(n.kind)&&te(u,n));if(l!==void 0&&c.length===0)return{record:l,action:"ignore"};const d=n,g=c.map(u=>u.id),v=o.map(u=>g.includes(u.id)?{...u,state:"superseded",updatedAt:i}:u),A=[...v,d],b=[...v.filter((u,x)=>u!==o[x]).map(u=>({schemaVersion:m,type:"upsert",record:u})),{schemaVersion:m,type:"upsert",record:d}];if(A.length>h.memoryRecords)throw new Error("Memory capacity reached. Forget or clear memories before adding more.");return await this.append(r,b),await this.writeIndex(r,A),{record:d,action:g.length>0?"supersede":"insert"}},w())}async forget(e,t){const r=this.resolvePaths(e);return y(r.journalFile,async()=>{const i=await this.readRecords(r,!0),n=i.filter(o=>o.id!==t);return n.length===i.length?!1:(await this.replaceJournal(r,n),await this.writeIndex(r,n),await this.pruneSemanticIndex(r,n),!0)},w())}async clear(e){const t=this.resolvePaths(e);return y(t.journalFile,async()=>{const r=await this.readRecords(t,!0);return r.length===0?0:(await this.replaceJournal(t,[]),await this.writeIndex(t,[]),await this.pruneSemanticIndex(t,[]),r.length)},w())}async markRetrieved(e,t){if(t.length===0)return;const r=this.resolvePaths(e);await y(r.journalFile,async()=>{const i=new Set(t),n=I(),o=await this.readRecords(r,!0),a=o.map(c=>i.has(c.id)?{...c,retrievalCount:c.retrievalCount+1,lastRetrievedAt:n,updatedAt:n}:c),p=a.filter((c,l)=>c!==o[l]).map(c=>({schemaVersion:m,type:"upsert",record:c}));p.length!==0&&(await this.append(r,p),await this.writeIndex(r,a))},w())}async export(e){return{schemaVersion:m,exportedAt:I(),records:await this.list(e)}}async import(e,t){const r=D(t),i=this.resolvePaths(e);return y(i.journalFile,async()=>{const n=await this.readRecords(i,!0),o=new Set(n.map(d=>d.id)),a=new Set(n.map(f)),p=r.records.filter(d=>!o.has(d.id)&&!a.has(f(d)));if(n.length+p.length>h.memoryRecords)throw new Error("Import exceeds the local memory capacity.");const c=I(),l=p.map(d=>({...d,source:"imported",state:"active",updatedAt:c}));if(l.length>0){const d=[...n,...l];await this.append(i,l.map(g=>({schemaVersion:m,type:"upsert",record:g}))),await this.writeIndex(i,d)}return{imported:l.length,skipped:r.records.length-l.length}},w())}resolvePaths(e){const t=S.join(this.paths.projectsDir,W(e,this.paths.platform),"memory");return{directory:t,journalFile:S.join(t,"journal.jsonl"),indexFile:S.join(t,"index.json"),semanticIndexFile:S.join(t,"semantic-index.json")}}async readRecords(e,t=!1){if(!t)return y(e.journalFile,()=>this.readRecords(e,!0),w());const r=await C(e.journalFile),i=await this.readIndex(e.indexFile);if(i?.journalFingerprint===r)return i.records;const n=Q(await this.readJournal(e.journalFile));return await this.writeIndex(e,n),this.logger?.info("memory.index.rebuilt",{projectKey:Z(e.directory),count:n.length}),n}async readSearchIndex(e,t){const r=await this.readIndex(e.indexFile);return r!==void 0&&r.records.length===t.length&&r.records.every((n,o)=>n.id===t[o]?.id&&n.updatedAt===t[o]?.updatedAt)?r.search:z(t)}async readIndex(e){try{const t=await k(e,h.memoryIndexBytes);return q(t)}catch(t){return O(t),void 0}}async readJournal(e){let t;try{if((await j.stat(e)).size>h.memoryJournalBytes)throw new Error("Memory journal exceeds the supported size limit. Export and clear memory before continuing.");t=await j.readFile(e,"utf8")}catch(r){if(O(r))return[];throw r}try{return N(t)}catch(r){if(!t.endsWith(`
+`))return await new Promise(i=>setImmediate(i)),N(await j.readFile(e,"utf8"));throw r}}async append(e,t){if(t.length===0)return;await j.mkdir(e.directory,{recursive:!0});const r=t.map(n=>JSON.stringify(n)).join(`
+`).concat(`
+`);if(await X(e.journalFile)+Buffer.byteLength(r,"utf8")>h.memoryJournalBytes)throw new Error("Memory journal exceeds the supported size limit. Export and clear memory before continuing.");await j.appendFile(e.journalFile,r,{encoding:"utf8",mode:384})}async replaceJournal(e,t){const r=t.map(n=>({schemaVersion:m,type:"upsert",record:n})),i=r.length===0?"":`${r.map(n=>JSON.stringify(n)).join(`
+`)}
+`;if(Buffer.byteLength(i,"utf8")>h.memoryJournalBytes)throw new Error("Memory journal exceeds the supported size limit.");await E(e.journalFile,i)}async writeIndex(e,t,r=z(t)){const i={schemaVersion:m,journalFingerprint:await C(e.journalFile),records:t,search:r,...$(t),updatedAt:I()},n=`${JSON.stringify(i,null,2)}
+`;if(Buffer.byteLength(n,"utf8")>h.memoryIndexBytes)throw new Error("Memory index exceeds the supported size limit.");await E(e.indexFile,n)}async pruneSemanticIndex(e,t){const r=await J(e.semanticIndexFile);if(r===void 0)return;const i=new Map(t.map(o=>[o.id,o])),n=Object.fromEntries(Object.entries(r.entries).filter(([o,a])=>i.get(o)!==void 0&&f(i.get(o))===a.contentHash));await E(e.semanticIndexFile,`${JSON.stringify({...r,entries:n,updatedAt:I()})}
+`)}}function N(s){return s.split(/\r?\n/u).filter(Boolean).map(e=>Y(JSON.parse(e)))}function Y(s){if(typeof s!="object"||s===null||Array.isArray(s))throw new Error("Invalid memory journal entry.");const e=s;if(e.schemaVersion!==m||e.type!=="upsert")throw new Error("Unsupported memory journal entry.");return{schemaVersion:m,type:"upsert",record:B(e.record)}}function q(s){if(typeof s!="object"||s===null||Array.isArray(s))return;const e=s;if(!(e.schemaVersion!==m||typeof e.journalFingerprint!="string"||typeof e.updatedAt!="string"||!Array.isArray(e.records)))try{const t=e.records.map(i=>B(i)),r=z(t);return{schemaVersion:m,journalFingerprint:e.journalFingerprint,records:t,search:r,...$(t),updatedAt:e.updatedAt}}catch{return}}async function J(s){try{const e=await k(s,h.memoryIndexBytes);if(typeof e!="object"||e===null||Array.isArray(e))return;const t=e;if(t.schemaVersion!==m||typeof t.model!="string"||typeof t.updatedAt!="string"||typeof t.entries!="object"||t.entries===null||Array.isArray(t.entries))return;const r={};for(const[i,n]of Object.entries(t.entries)){if(typeof n!="object"||n===null||Array.isArray(n))return;const o=n;if(typeof o.contentHash!="string"||!Array.isArray(o.vector)||o.vector.some(a=>typeof a!="number"||!Number.isFinite(a)))return;r[i]={contentHash:o.contentHash,vector:o.vector}}return{schemaVersion:m,model:t.model,entries:r,updatedAt:t.updatedAt}}catch{return}}function P(s){if(s.length===0||s.length>4096||s.some(e=>!Number.isFinite(e)))throw new Error("Embedding vector is invalid.")}function G(s,e){if(s.length!==e.length)return-1;let t=0,r=0,i=0;for(let n=0;n<s.length;n+=1)t+=s[n]*e[n],r+=s[n]**2,i+=e[n]**2;return r===0||i===0?0:t/Math.sqrt(r*i)}function Q(s){const e=new Map;for(const t of s)e.set(t.record.id,t.record);return[...e.values()]}function $(s){const e=Object.fromEntries(T.map(r=>[r,s.filter(i=>i.kind===r).map(i=>i.id)])),t=Object.fromEntries(["active","superseded","expired"].map(r=>[r,s.filter(i=>i.state===r).map(i=>i.id)]));return{activeIds:s.filter(r=>r.state==="active").map(r=>r.id),kindIds:e,stateIds:t}}async function X(s){try{return(await j.stat(s)).size}catch(e){if(O(e))return 0;throw e}}async function C(s){try{const e=await j.stat(s);return`${e.size}:${e.mtimeMs}`}catch(e){if(O(e))return"missing";throw e}}function f(s){return V.createHash("sha256").update(`${s.kind}\0${s.statement.trim().toLocaleLowerCase()}\0${s.topics.join("\0")}`,"utf8").digest("hex")}function Z(s){return V.createHash("sha256").update(s,"utf8").digest("hex").slice(0,16)}function ee(s){return U(s).consolidationPolicy==="retain-on-conflict"}function te(s,e){if(s.topics.length===0||e.topics.length===0)return!1;const t=new Set(s.topics);return e.topics.some(r=>t.has(r))}function w(){return{userMessage:"Memory is being updated by another LotaGate process. Try again shortly."}}function I(){return new Date().toISOString()}export{pe as FileMemoryStore};

package/dist/infrastructure/network/safe-media-downloader.d.ts

@@ -0,0 +1,23 @@
+import https from 'node:https';
+export interface DownloadedMedia {
+    readonly bytes: Uint8Array;
+    readonly contentType: string | undefined;
+}
+export interface PublicMediaAddress {
+    readonly address: string;
+    readonly family: 4 | 6;
+}
+export interface PublicMediaDownloaderDependencies {
+    resolveAddresses?: (hostname: string) => Promise<readonly PublicMediaAddress[]>;
+    request?: typeof https.request;
+}
+interface DownloadOptions {
+    readonly maxBytes: number;
+    readonly timeoutMs: number;
+    readonly signal?: AbortSignal | undefined;
+}
+/** Downloads a generated artifact only through a verified public HTTPS address. */
+export declare function downloadPublicMedia(rawUrl: string | undefined, options: DownloadOptions): Promise<DownloadedMedia>;
+/** Creates an isolated downloader for CLI infrastructure tests and alternate Node transports. */
+export declare function createPublicMediaDownloader(dependencies?: PublicMediaDownloaderDependencies): (rawUrl: string | undefined, options: DownloadOptions) => Promise<DownloadedMedia>;
+export {};

package/dist/infrastructure/network/safe-media-downloader.js

@@ -0,0 +1 @@
+import{lookup as v}from"node:dns/promises";import E from"node:https";import{isIP as L}from"node:net";import{CliError as h}from"../../domain/errors/cli-error.js";import{CLI_ERROR_CODES as b}from"../../domain/errors/error-codes.js";async function H(e,t){return I()(e,t)}function I(e={}){const t=e.resolveAddresses??P,r=e.request??E.request;return async(o,n)=>{const s=g(o);return D(n,async d=>{const l=await R(s.hostname,t,d,n.signal),i=await A(s,l,r,d,n.signal);if(i.statusCode===void 0||i.statusCode<200||i.statusCode>=300)throw i.destroy(),f(`Image download failed with HTTP ${i.statusCode??"unknown"}.`);const a=i.headers["content-length"],c=Array.isArray(a)?a[0]:a;if(c!==void 0&&(!/^\d+$/u.test(c)||Number(c)>n.maxBytes))throw i.destroy(),f("Downloaded image exceeds the supported output limit.");return{bytes:await C(i,n.maxBytes,d,n.signal),contentType:$(i.headers["content-type"])}})}}function g(e){if(e===void 0)throw f("The provider returned an image without Base64 data or a download URL.");let t;try{t=new URL(e)}catch{throw f("The provider returned an invalid image download URL.")}if(t.protocol!=="https:"||t.username||t.password||t.port!==""&&t.port!=="443")throw f("Image download URLs must use public HTTPS on port 443.");return t}async function R(e,t,r,o){if(e.toLowerCase()==="localhost")throw f("Image download URL must not target localhost.");const n=await U(t(e),r,o);if(n.length===0||n.some(s=>!B(s.address)))throw f("Image download URL must resolve only to public network addresses.");return n}async function P(e){return(await v(e,{all:!0,verbatim:!0})).map(r=>({address:r.address,family:r.family===6?6:4}))}async function A(e,t,r,o,n){let s;for(const l of t)try{return await T(e,l,r,o,n)}catch(i){if(o.aborted)throw m(n);s=i}const d=s instanceof Error&&s.message.length>0?`: ${s.message}`:"";throw f(`Image download failed${d}`)}function T(e,t,r,o,n){return new Promise((s,d)=>{let l=!1,i;const a=u=>{l||(l=!0,o.removeEventListener("abort",c),u())},c=()=>{const u=m(n);i?.destroy(u),a(()=>d(u))};try{i=r({protocol:"https:",hostname:e.hostname,port:443,path:`${e.pathname}${e.search}`,method:"GET",servername:e.hostname,lookup:(u,p,w)=>{p.all===!0?w(null,[{address:t.address,family:t.family}]):w(null,t.address,t.family)}},u=>a(()=>s(u))),i.once("error",u=>a(()=>d(u))),o.aborted?c():o.addEventListener("abort",c,{once:!0}),i.end()}catch(u){a(()=>d(u))}})}async function C(e,t,r,o){const n=[];let s=0;const d=()=>{e.destroy()};r.aborted?d():r.addEventListener("abort",d,{once:!0});try{for await(const a of e){if(r.aborted)throw m(o);const c=Buffer.isBuffer(a)?a:Buffer.from(a);if(s+=c.byteLength,s>t)throw e.destroy(),f("Downloaded image exceeds the supported output limit.");n.push(c)}}catch(a){throw r.aborted?m(o):a instanceof h?a:f(a instanceof Error?`Image download failed: ${a.message}`:"Image download failed.")}finally{r.removeEventListener("abort",d)}if(r.aborted)throw m(o);const l=new Uint8Array(s);let i=0;for(const a of n)l.set(a,i),i+=a.byteLength;return l}async function D(e,t){const r=new AbortController,o=setTimeout(()=>r.abort(new Error("Image download timed out.")),e.timeoutMs),n=()=>r.abort(e.signal?.reason);e.signal?.aborted?n():e.signal?.addEventListener("abort",n,{once:!0});try{return await t(r.signal)}finally{clearTimeout(o),e.signal?.removeEventListener("abort",n)}}async function U(e,t,r){if(t.aborted)throw m(r);return new Promise((o,n)=>{const s=()=>{t.removeEventListener("abort",s),n(m(r))};t.addEventListener("abort",s,{once:!0}),e.then(d=>{t.removeEventListener("abort",s),o(d)},d=>{t.removeEventListener("abort",s),n(d)})})}function $(e){return(Array.isArray(e)?e[0]:e)?.split(";",1)[0]?.trim()||void 0}function B(e){const t=L(e);return t===4?y(e):t===6?k(e):!1}function y(e){const t=e.split(".").map(Number),[r,o]=t;return!(r===void 0||o===void 0||r===0||r===10||r===127||r>=224||r===100&&o>=64&&o<=127||r===169&&o===254||r===172&&o>=16&&o<=31||r===192&&o===168||r===198&&(o===18||o===19))}function k(e){const t=e.toLowerCase();if(t==="::"||t==="::1"||t.startsWith("fe80:")||t.startsWith("fc")||t.startsWith("fd"))return!1;const r=t.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/u);return r===null||y(r[1])}function m(e){return e?.aborted?q(e.reason):f("Image download timed out.")}function q(e){return new h(b.INTERRUPTED,"Media command interrupted.",{category:"media",userMessage:"Media command interrupted.",retryable:!0,cause:e})}function f(e){return new h(b.INVALID_ARGUMENT,e,{category:"media",userMessage:e})}export{I as createPublicMediaDownloader,H as downloadPublicMedia};