@lotagate/cli 0.1.21 → 0.1.22

package/dist/infrastructure/sessions/session-index.js

@@ -0,0 +1,84 @@
+import path from 'node:path';
+import { atomicWriteFile, withFileLock } from '../filesystem/atomic-file-store.js';
+import { isFileNotFound } from '../filesystem/fs-errors.js';
+import { resolveProjectSessionPathsForKey } from './project-session-paths.js';
+import { readJsonFileBounded } from '../filesystem/bounded-json-reader.js';
+import { RESOURCE_LIMITS } from '../../domain/runtime/resource-limits.js';
+export async function readProjectSessionIndex(filePath, projectKey) {
+    try {
+        const value = readProjectIndex(await readJsonFileBounded(filePath, RESOURCE_LIMITS.configFileBytes), projectKey);
+        return value;
+    }
+    catch (error) {
+        if (isFileNotFound(error))
+            return { projectKey, sessions: {} };
+        throw error;
+    }
+}
+export async function writeProjectSessionIndex(filePath, projectKey, sessions) {
+    await atomicWriteFile(filePath, `${JSON.stringify({ projectKey, sessions }, null, 2)}\n`);
+}
+export async function readSessionLocator(paths) {
+    const filePath = path.join(paths.projectsDir, 'locator.json');
+    try {
+        return readLocatorIndex(await readJsonFileBounded(filePath, RESOURCE_LIMITS.configFileBytes));
+    }
+    catch (error) {
+        if (isFileNotFound(error))
+            return { sessions: {} };
+        throw error;
+    }
+}
+function readProjectIndex(value, projectKey) {
+    if (!isRecord(value) || value['projectKey'] !== projectKey || !isRecord(value['sessions']))
+        throw new Error('Invalid project session index.');
+    for (const metadata of Object.values(value['sessions']))
+        if (!isSessionMetadata(metadata))
+            throw new Error('Invalid project session metadata.');
+    return { projectKey, sessions: value['sessions'] };
+}
+function readLocatorIndex(value) {
+    if (!isRecord(value) || !isRecord(value['sessions']) || Object.values(value['sessions']).some((projectKey) => typeof projectKey !== 'string'))
+        throw new Error('Invalid session locator index.');
+    return { sessions: value['sessions'] };
+}
+function isSessionMetadata(value) {
+    if (!isRecord(value))
+        return false;
+    return typeof value['id'] === 'string' && typeof value['projectFingerprint'] === 'string' && typeof value['cwd'] === 'string'
+        && (typeof value['model'] === 'string' || value['model'] === null) && (typeof value['profile'] === 'string' || value['profile'] === null)
+        && (value['status'] === 'active' || value['status'] === 'completed' || value['status'] === 'failed' || value['status'] === 'cancelled')
+        && typeof value['createdAt'] === 'string' && typeof value['updatedAt'] === 'string';
+}
+function isRecord(value) { return typeof value === 'object' && value !== null && !Array.isArray(value); }
+export async function writeSessionLocator(paths, sessions) {
+    await atomicWriteFile(path.join(paths.projectsDir, 'locator.json'), `${JSON.stringify({ sessions }, null, 2)}\n`);
+}
+export async function indexProjectSession(paths, metadata, projectKey) {
+    const projectPaths = resolveProjectSessionPathsForKey(paths, projectKey, metadata.id);
+    await withFileLock(projectPaths.projectIndexFile, async () => {
+        const projectIndex = await readProjectSessionIndex(projectPaths.projectIndexFile, projectKey);
+        await writeProjectSessionIndex(projectPaths.projectIndexFile, projectKey, { ...projectIndex.sessions, [metadata.id]: metadata });
+    });
+    const locatorFile = path.join(paths.projectsDir, 'locator.json');
+    await withFileLock(locatorFile, async () => {
+        const locator = await readSessionLocator(paths);
+        await writeSessionLocator(paths, { ...locator.sessions, [metadata.id]: projectKey });
+    });
+}
+export async function removeIndexedSession(paths, metadata, projectKey) {
+    const projectPaths = resolveProjectSessionPathsForKey(paths, projectKey, metadata.id);
+    await withFileLock(projectPaths.projectIndexFile, async () => {
+        const projectIndex = await readProjectSessionIndex(projectPaths.projectIndexFile, projectKey);
+        const sessions = { ...projectIndex.sessions };
+        delete sessions[metadata.id];
+        await writeProjectSessionIndex(projectPaths.projectIndexFile, projectKey, sessions);
+    });
+    const locatorFile = path.join(paths.projectsDir, 'locator.json');
+    await withFileLock(locatorFile, async () => {
+        const locator = await readSessionLocator(paths);
+        const locations = { ...locator.sessions };
+        delete locations[metadata.id];
+        await writeSessionLocator(paths, locations);
+    });
+}

package/dist/infrastructure/sessions/session-journal.d.ts

@@ -0,0 +1,22 @@
+import type { SessionEvent, SessionMetadata, TranscriptEntry } from '../../domain/session/session.js';
+export type SessionJournalRecord = {
+    recordType: 'metadata';
+    metadata: SessionMetadata;
+} | {
+    recordType: 'event';
+    event: SessionEvent;
+} | {
+    recordType: 'transcript';
+    entry: TranscriptEntry;
+};
+export declare function metadataRecord(metadata: SessionMetadata): SessionJournalRecord;
+export declare function eventRecord(event: SessionEvent): SessionJournalRecord;
+export declare function transcriptRecord(entry: TranscriptEntry): SessionJournalRecord;
+export declare function appendJournalRecord(filePath: string, record: SessionJournalRecord): Promise<void>;
+/** Appends one crash-consistent physical JSONL record for an ordered logical batch. */
+export declare function appendJournalRecords(filePath: string, records: readonly SessionJournalRecord[]): Promise<void>;
+export declare function readJournal(filePath: string): Promise<readonly SessionJournalRecord[]>;
+export declare function latestMetadata(records: readonly SessionJournalRecord[]): SessionMetadata | undefined;
+export declare function journalEvents(records: readonly SessionJournalRecord[]): readonly SessionEvent[];
+export declare function journalTranscript(records: readonly SessionJournalRecord[]): readonly TranscriptEntry[];
+export declare function repairJournal(filePath: string): Promise<number>;

package/dist/infrastructure/sessions/session-journal.js

@@ -0,0 +1,137 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { isFileNotFound } from '../filesystem/fs-errors.js';
+import { atomicWriteFile } from '../filesystem/atomic-file-store.js';
+import { isRecord, isSessionEvent, isSessionMetadata, isTranscriptEntry } from '../../domain/session/session-schema.js';
+import { RESOURCE_LIMITS } from '../../domain/runtime/resource-limits.js';
+export function metadataRecord(metadata) {
+    return { recordType: 'metadata', metadata };
+}
+export function eventRecord(event) {
+    return { recordType: 'event', event };
+}
+export function transcriptRecord(entry) {
+    return { recordType: 'transcript', entry };
+}
+export async function appendJournalRecord(filePath, record) {
+    await appendSerializedRecord(filePath, record);
+}
+/** Appends one crash-consistent physical JSONL record for an ordered logical batch. */
+export async function appendJournalRecords(filePath, records) {
+    if (records.length === 0)
+        return;
+    await appendSerializedRecord(filePath, records.length === 1 ? records[0] : { recordType: 'batch', records });
+}
+async function appendSerializedRecord(filePath, record) {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    const serialized = `${JSON.stringify(record)}\n`;
+    await assertJournalCanAppend(filePath, Buffer.byteLength(serialized, 'utf8'));
+    await fs.appendFile(filePath, serialized, { encoding: 'utf8', mode: 0o600 });
+}
+export async function readJournal(filePath) {
+    let raw;
+    try {
+        await assertJournalCanRead(filePath);
+        raw = await fs.readFile(filePath, 'utf8');
+    }
+    catch (error) {
+        if (isFileNotFound(error))
+            return [];
+        throw error;
+    }
+    try {
+        return parseJournal(raw);
+    }
+    catch (error) {
+        if (!hasIncompleteTrailingLine(raw))
+            throw error;
+        await new Promise((resolve) => setImmediate(resolve));
+        return parseJournal(await fs.readFile(filePath, 'utf8'));
+    }
+}
+function parseJournal(raw) {
+    return raw.split(/\r?\n/u).filter(Boolean).flatMap((line) => parseJournalLine(JSON.parse(line)));
+}
+function hasIncompleteTrailingLine(raw) {
+    const normalized = raw.replace(/\r\n/gu, '\n');
+    return normalized.length > 0 && !normalized.endsWith('\n');
+}
+async function assertJournalCanRead(filePath) {
+    const stat = await fs.stat(filePath);
+    if (stat.size > RESOURCE_LIMITS.sessionJournalBytes)
+        throw new Error('Session journal exceeds the supported size limit. Repair or export the session before resuming it.');
+}
+async function assertJournalCanAppend(filePath, additionalBytes) {
+    let size = 0;
+    try {
+        size = (await fs.stat(filePath)).size;
+    }
+    catch (error) {
+        if (!isFileNotFound(error))
+            throw error;
+    }
+    if (size + additionalBytes > RESOURCE_LIMITS.sessionJournalBytes)
+        throw new Error('Session journal exceeds the supported size limit. Compact or export the session before adding more data.');
+}
+export function latestMetadata(records) {
+    return records.filter((record) => record.recordType === 'metadata').at(-1)?.metadata;
+}
+export function journalEvents(records) {
+    return records.filter((record) => record.recordType === 'event').map((record) => record.event);
+}
+export function journalTranscript(records) {
+    return records.filter((record) => record.recordType === 'transcript').map((record) => record.entry);
+}
+export async function repairJournal(filePath) {
+    let raw;
+    try {
+        raw = await fs.readFile(filePath, 'utf8');
+    }
+    catch (error) {
+        if (isFileNotFound(error))
+            return 0;
+        throw error;
+    }
+    const lines = raw.split(/\r?\n/u);
+    const valid = [];
+    let removed = 0;
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index]?.trim();
+        if (line === undefined || line.length === 0)
+            continue;
+        try {
+            parseJournalLine(JSON.parse(line));
+            valid.push(line);
+        }
+        catch (error) {
+            const trailing = lines.slice(index + 1).every((candidate) => candidate.trim().length === 0);
+            if (!trailing)
+                throw error;
+            removed += 1;
+        }
+    }
+    if (removed > 0)
+        await atomicWriteFile(filePath, valid.length === 0 ? '' : `${valid.join('\n')}\n`);
+    return removed;
+}
+function parseJournalLine(value) {
+    if (isRecord(value) && value['recordType'] === 'batch') {
+        const records = value['records'];
+        if (!Array.isArray(records) || records.length === 0)
+            throw new Error('Invalid session journal batch.');
+        return records.map(parseJournalRecord);
+    }
+    return [parseJournalRecord(value)];
+}
+function parseJournalRecord(value) {
+    if (!isRecord(value))
+        throw new Error('Invalid session journal record.');
+    const record = value;
+    if (record['recordType'] === 'metadata' && isSessionMetadata(record['metadata']))
+        return { recordType: 'metadata', metadata: record['metadata'] };
+    if (record['recordType'] === 'event' && isSessionEvent(record['event']))
+        return { recordType: 'event', event: record['event'] };
+    if (record['recordType'] === 'transcript' && isTranscriptEntry(record['entry']))
+        return { recordType: 'transcript', entry: record['entry'] };
+    throw new Error('Unsupported or malformed session journal record.');
+}

package/dist/infrastructure/sessions/subagent-journal-store.d.ts

@@ -0,0 +1,28 @@
+import type { PlatformPaths } from '../platform/platform-paths.js';
+import type { SubagentResult } from '../../domain/orchestration/subagent.js';
+export type SubagentJournalRecord = {
+    recordType: 'created';
+    id: string;
+    displayName: string;
+    task: string;
+    mode: 'research' | 'worker';
+    model: string;
+    timestamp: string;
+} | {
+    recordType: 'started';
+    id: string;
+    displayName: string;
+    mode: 'research' | 'worker';
+    model: string;
+    timestamp: string;
+} | {
+    recordType: 'completed' | 'completed_with_warning' | 'failed' | 'cancelled';
+    result: SubagentResult;
+    timestamp: string;
+};
+/** Persists bounded child-agent lifecycle records beside the parent session. */
+export declare class SubagentJournalStore {
+    private readonly paths;
+    constructor(paths: PlatformPaths);
+    append(parentSessionId: string, cwd: string, record: SubagentJournalRecord): Promise<void>;
+}

package/dist/infrastructure/sessions/subagent-journal-store.js

@@ -0,0 +1,30 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { resolveProjectSessionPaths } from './project-session-paths.js';
+/** Persists bounded child-agent lifecycle records beside the parent session. */
+export class SubagentJournalStore {
+    paths;
+    constructor(paths) {
+        this.paths = paths;
+    }
+    async append(parentSessionId, cwd, record) {
+        assertSafeSessionId(parentSessionId);
+        const location = resolveProjectSessionPaths(this.paths, cwd, parentSessionId);
+        const filePath = path.join(location.subagentsDirectory, `${recordId(record)}.jsonl`);
+        await fs.mkdir(location.subagentsDirectory, { recursive: true, mode: 0o700 });
+        await appendBoundedRecord(filePath, record);
+    }
+}
+function assertSafeSessionId(value) {
+    if (!/^[A-Za-z0-9._-]{1,128}$/u.test(value))
+        throw new Error('Invalid parent session id for subagent journal.');
+}
+async function appendBoundedRecord(filePath, record) {
+    const serialized = `${JSON.stringify(record)}\n`;
+    if (Buffer.byteLength(serialized, 'utf8') > 32 * 1024)
+        throw new Error('Subagent journal record exceeds the configured limit.');
+    await fs.appendFile(filePath, serialized, { encoding: 'utf8', mode: 0o600 });
+}
+function recordId(record) {
+    return record.recordType === 'created' || record.recordType === 'started' ? record.id : record.result.id;
+}

package/dist/infrastructure/shell/shell-tool-executor.d.ts

@@ -0,0 +1,17 @@
+import type { ToolDefinition } from '@lotagate/sdk';
+import type { ToolExecutionContext, ToolExecutor, ToolInfo, ToolResult } from '@lotagate/agent-sdk';
+import type { ToolActivityObserver } from '../../ports/tool-activity.js';
+import { type HostPlatformContext } from '../platform/host-platform.js';
+/** Exposes the same shell capability definitions to runtime and context accounting. */
+export declare function shellToolDefinitions(): readonly ToolDefinition[];
+export declare class ShellToolExecutor implements ToolExecutor {
+    private readonly options;
+    constructor(options?: {
+        onActivity?: ToolActivityObserver;
+        readOnly?: boolean;
+        platform?: HostPlatformContext;
+    });
+    listTools(): readonly ToolDefinition[];
+    getToolInfo(toolName: string): ToolInfo | undefined;
+    execute(toolName: string, input: Record<string, unknown>, context: ToolExecutionContext): Promise<ToolResult>;
+}

package/dist/infrastructure/shell/shell-tool-executor.js

@@ -0,0 +1,115 @@
+import { resolveWorkspacePath } from '../filesystem/path-resolver.js';
+import { isReadOnlyShellRequest } from '../../application/security/tool-risk-classifier.js';
+import { detectHostPlatform } from '../platform/host-platform.js';
+import { createSafeChildEnvironment, spawnPlatformProcess, terminatePlatformProcess } from '../platform/host-process.js';
+import { formatShellCommandForDisplay } from '../../application/agent/tool-display.js';
+const SHELL_TOOLS = [
+    { type: 'function', function: {
+            name: 'shell.exec',
+            description: 'Execute one program with structured arguments inside the trusted workspace. Shell interpretation is disabled.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    command: { type: 'string', description: 'Executable name or path.' },
+                    args: { type: 'array', items: { type: 'string' }, description: 'Structured process arguments.' },
+                    cwd: { type: 'string', description: 'Optional workspace-relative working directory.' },
+                    timeoutMs: { type: 'number', description: 'Timeout between 100 and 120000 milliseconds.' },
+                },
+                required: ['command'],
+                additionalProperties: false,
+            },
+        } },
+];
+/** Exposes the same shell capability definitions to runtime and context accounting. */
+export function shellToolDefinitions() { return SHELL_TOOLS; }
+export class ShellToolExecutor {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    listTools() { return shellToolDefinitions(); }
+    getToolInfo(toolName) {
+        return toolName === 'shell.exec' ? { toolName, source: 'shell', executorId: 'local-shell' } : undefined;
+    }
+    async execute(toolName, input, context) {
+        if (toolName !== 'shell.exec')
+            return { content: `Unknown shell tool: ${toolName}`, isError: true };
+        if (typeof input['command'] !== 'string' || input['command'].trim().length === 0)
+            return { content: 'shell.exec requires a command.', isError: true };
+        const args = input['args'] === undefined ? [] : input['args'];
+        if (!Array.isArray(args) || args.some((arg) => typeof arg !== 'string'))
+            return { content: 'shell.exec args must be an array of strings.', isError: true };
+        if (this.options.readOnly && !isReadOnlyShellRequest(input['command'], args))
+            return { content: 'This subagent is limited to read-only shell commands.', isError: true };
+        const timeoutMs = typeof input['timeoutMs'] === 'number' ? Math.min(Math.max(input['timeoutMs'], 100), 120_000) : 30_000;
+        const cwd = await resolveWorkspacePath(input['cwd'] ?? '.', context);
+        const command = formatShellCommandForDisplay(input['command'], args);
+        const activity = this.options.onActivity?.start({ key: `${context.runId}:shell.exec`, toolName: 'shell.exec', source: 'shell', label: command });
+        return runProcess(input['command'], args, cwd, timeoutMs, context, this.options.platform ?? detectHostPlatform()).then((result) => {
+            activity?.complete(result.isError === true);
+            return result;
+        });
+    }
+}
+function runProcess(command, args, cwd, timeoutMs, context, platform) {
+    return new Promise((resolve) => {
+        const child = spawnPlatformProcess(command, args, platform, {
+            cwd,
+            detached: platform.supportsProcessGroups,
+            env: createSafeChildEnvironment(platform),
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        const stdout = [];
+        const stderr = [];
+        let settled = false;
+        let timedOut = false;
+        let outputExceeded = false;
+        let outputBytes = 0;
+        const outputLimit = Math.max(0, Math.floor(context.maxResultBytes));
+        const appendOutput = (target, chunk) => {
+            if (outputExceeded || chunk.byteLength === 0)
+                return;
+            const remaining = outputLimit - outputBytes;
+            if (remaining <= 0) {
+                outputExceeded = true;
+                terminatePlatformProcess(child, platform);
+                return;
+            }
+            const accepted = chunk.subarray(0, remaining);
+            target.push(accepted);
+            outputBytes += accepted.byteLength;
+            if (accepted.byteLength < chunk.byteLength) {
+                outputExceeded = true;
+                terminatePlatformProcess(child, platform);
+            }
+        };
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            context.signal?.removeEventListener('abort', abort);
+            resolve(result);
+        };
+        const abort = () => { terminatePlatformProcess(child, platform); finish({ content: 'Process cancelled.', isError: true }); };
+        const timer = setTimeout(() => { timedOut = true; terminatePlatformProcess(child, platform); }, timeoutMs);
+        child.stdout?.on('data', (chunk) => appendOutput(stdout, chunk));
+        child.stderr?.on('data', (chunk) => appendOutput(stderr, chunk));
+        child.once('error', (error) => finish({ content: redact(error.message), isError: true }));
+        child.once('close', (code) => {
+            if (timedOut)
+                finish({ content: `Process timed out after ${timeoutMs}ms.`, isError: true });
+            else if (outputExceeded)
+                finish({ content: 'Process output exceeded the configured limit.', isError: true });
+            else
+                finish({ content: redact(`${Buffer.concat(stdout).toString('utf8')}${Buffer.concat(stderr).toString('utf8')}${code === 0 ? '' : `\nProcess exited with code ${String(code)}.`}`), isError: code !== 0 });
+        });
+        if (context.signal?.aborted === true)
+            abort();
+        else
+            context.signal?.addEventListener('abort', abort, { once: true });
+    });
+}
+function redact(value) {
+    return value.replace(/Bearer\s+[^\s]+/gi, 'Bearer [REDACTED]').replace(/sk-[A-Za-z0-9_-]{8,}/g, '[REDACTED]');
+}

package/dist/infrastructure/tokens/tiktoken-token-estimator.d.ts

@@ -0,0 +1,18 @@
+import type { ChatUsage } from '../../ports/chat-model.js';
+export interface TokenEstimateInput {
+    model: string;
+    prompt: string;
+    response: string;
+}
+export interface TextTokenEstimateInput {
+    model: string;
+    text: string;
+}
+/**
+ * Estimates turn usage when an upstream provider does not include usage in the
+ * streaming protocol. The result is deliberately marked as estimated because
+ * providers may use a tokenizer different from the OpenAI tokenizer family.
+ */
+export declare function estimateTurnUsage(input: TokenEstimateInput): ChatUsage | undefined;
+/** Estimates one text payload with the same tokenizer used for turn fallback accounting. */
+export declare function estimateTextTokens(input: TextTokenEstimateInput): number;

package/dist/infrastructure/tokens/tiktoken-token-estimator.js

@@ -0,0 +1,48 @@
+import { encoding_for_model, get_encoding } from 'tiktoken';
+const FALLBACK_ENCODING = 'o200k_base';
+/**
+ * Estimates turn usage when an upstream provider does not include usage in the
+ * streaming protocol. The result is deliberately marked as estimated because
+ * providers may use a tokenizer different from the OpenAI tokenizer family.
+ */
+export function estimateTurnUsage(input) {
+    try {
+        const encoder = createEncoder(input.model);
+        try {
+            const promptTokens = encoder.encode(input.prompt).length;
+            const completionTokens = encoder.encode(input.response).length;
+            return { promptTokens, completionTokens, totalTokens: promptTokens + completionTokens, estimated: true };
+        }
+        finally {
+            encoder.free();
+        }
+    }
+    catch {
+        // Token accounting must never make a successfully streamed response fail.
+        return undefined;
+    }
+}
+/** Estimates one text payload with the same tokenizer used for turn fallback accounting. */
+export function estimateTextTokens(input) {
+    try {
+        const encoder = createEncoder(input.model);
+        try {
+            return encoder.encode(input.text).length;
+        }
+        finally {
+            encoder.free();
+        }
+    }
+    catch {
+        // A byte estimate keeps context diagnostics available for unsupported models.
+        return Math.ceil(Buffer.byteLength(input.text, 'utf8') / 4);
+    }
+}
+function createEncoder(model) {
+    try {
+        return encoding_for_model(model);
+    }
+    catch {
+        return get_encoding(FALLBACK_ENCODING);
+    }
+}

package/dist/infrastructure/workspace/workspace-settings-store.d.ts

@@ -0,0 +1,9 @@
+import { type WorkspaceSettings } from '../../domain/workspace/workspace-settings.js';
+export declare class WorkspaceSettingsStore {
+    ensureInitialized(cwd: string): Promise<void>;
+    load(cwd: string): Promise<WorkspaceSettings>;
+    /** Persist a user-approved rule in the ignored local project policy. */
+    rememberAllow(cwd: string, rule: string): Promise<void>;
+    private readOptional;
+    private createIfMissing;
+}

package/dist/infrastructure/workspace/workspace-settings-store.js

@@ -0,0 +1,75 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { DEFAULT_WORKSPACE_SETTINGS } from '../../domain/workspace/workspace-settings.js';
+import { permissionsFromSettings, validateSettingsDocument } from '../../domain/settings/settings-document.js';
+import { resolveProjectConfigPaths } from '../platform/platform-paths.js';
+import { atomicWriteFile, withFileLock } from '../filesystem/atomic-file-store.js';
+import { isAlreadyExists, isFileNotFound } from '../filesystem/fs-errors.js';
+import { readJsonFileBounded } from '../filesystem/bounded-json-reader.js';
+import { RESOURCE_LIMITS } from '../../domain/runtime/resource-limits.js';
+export class WorkspaceSettingsStore {
+    async ensureInitialized(cwd) {
+        const paths = resolveProjectConfigPaths(cwd);
+        await fs.mkdir(paths.directory, { recursive: true });
+        await Promise.all([paths.skillsDir, paths.pluginsDir, paths.hooksDir].map((directory) => fs.mkdir(directory, { recursive: true })));
+        await this.createIfMissing(paths.settings, DEFAULT_WORKSPACE_SETTINGS);
+        await this.createIfMissing(paths.localSettings, DEFAULT_WORKSPACE_SETTINGS);
+        await this.createIfMissing(path.join(paths.directory, '.gitignore'), 'settings.local.json\n');
+    }
+    async load(cwd) {
+        const paths = resolveProjectConfigPaths(cwd);
+        const [shared, local] = await Promise.all([this.readOptional(paths.settings), this.readOptional(paths.localSettings)]);
+        return { schemaVersion: 1, permissions: mergePermissions(shared?.permissions, local?.permissions) };
+    }
+    /** Persist a user-approved rule in the ignored local project policy. */
+    async rememberAllow(cwd, rule) {
+        const normalizedRule = rule.trim();
+        if (normalizedRule.length === 0)
+            return;
+        const paths = resolveProjectConfigPaths(cwd);
+        await fs.mkdir(paths.directory, { recursive: true });
+        await withFileLock(paths.localSettings, async () => {
+            const current = await this.readOptional(paths.localSettings) ?? DEFAULT_WORKSPACE_SETTINGS;
+            if (current.permissions.allow.includes(normalizedRule))
+                return;
+            const next = {
+                schemaVersion: 1,
+                permissions: {
+                    ...current.permissions,
+                    allow: [...current.permissions.allow, normalizedRule],
+                },
+            };
+            await atomicWriteFile(paths.localSettings, `${JSON.stringify(next, null, 2)}\n`);
+        });
+    }
+    async readOptional(filePath) {
+        try {
+            const document = validateSettingsDocument(await readJsonFileBounded(filePath, RESOURCE_LIMITS.workspaceSettingsBytes));
+            return { schemaVersion: 1, permissions: permissionsFromSettings(document) };
+        }
+        catch (error) {
+            if (isFileNotFound(error))
+                return undefined;
+            throw error;
+        }
+    }
+    async createIfMissing(filePath, value) {
+        try {
+            await fs.writeFile(filePath, typeof value === 'string' ? value : `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+        }
+        catch (error) {
+            if (!isAlreadyExists(error))
+                throw error;
+        }
+    }
+}
+function mergePermissions(shared, local) {
+    return {
+        allow: mergeRules(shared?.allow, local?.allow),
+        ask: mergeRules(shared?.ask, local?.ask),
+        deny: mergeRules(shared?.deny, local?.deny),
+    };
+}
+function mergeRules(...values) {
+    return [...new Set(values.flatMap((items) => items ?? []))];
+}

package/dist/main.d.ts

@@ -0,0 +1,7 @@
+import type { Readable, Writable } from 'node:stream';
+export { CLI_VERSION } from './version.js';
+export declare function main(argv: readonly string[], io?: {
+    stdin?: Readable;
+    stdout?: Writable;
+    stderr?: Writable;
+}): Promise<number>;