sneakoscope 8.1.2 → 8.2.0

package/dist/core/image-ux-review/real-callout-extractor.js

@@ -1,11 +1,13 @@
+import fsp from 'node:fs/promises';
 import path from 'node:path';
-import { codexSchemaPath, runCodexExecResumeWithOutputSchema, structuredOutputBlocker } from '../codex-exec-output-schema.js';
+import { codexSchemaPath, runCodexExecResumeWithOutputSchema, structuredOutputBlocker, validateStructuredOutput } from '../codex-exec-output-schema.js';
 import { readJson } from '../fsx.js';
-import { runOpenAIStructuredOutput } from '../structured-output-adapter.js';
-import { resolveCodexLbImagegenTarget } from '../imagegen/codex-lb-imagegen-target.js';
+import { strictJsonSchemaFormat } from '../structured-output-adapter.js';
+import { parseResponsesSsePayload } from '../responses-stream.js';
+import { DESKTOP_BRIDGE_IMAGEGEN_RECOVERY_GUIDANCE, resolveDesktopBridgeImagegenTarget } from '../imagegen/desktop-bridge-imagegen-target.js';
 import { generatedImageMetadata } from './imagegen-adapter.js';
 import { buildIssueLedgerFromGeneratedCallouts } from './callout-extraction.js';
-export async function extractRealCallouts(input) {
+export async function extractRealCallouts(input, opts = {}) {
     const schemaPath = await codexSchemaPath('image-ux-issue-ledger');
     const jsonSchema = await readJson(schemaPath);
     const prompt = input.prompt || buildRealCalloutExtractionPrompt(input);
@@ -74,16 +76,39 @@ export async function extractRealCallouts(input) {
         });
     }
     else {
-        const codexLb = await resolveCodexLbImagegenTarget({}).catch(() => null);
-        const useCodexLb = codexLb?.selected === true && codexLb.blocker === null;
-        providerResult = await runOpenAIStructuredOutput({
-            prompt,
-            schemaName: 'image_ux_issue_ledger',
-            jsonSchema,
-            imagePath: path.resolve(input.root, input.generatedImagePath),
-            ...(useCodexLb ? { baseUrl: codexLb.base_url, apiKey: codexLb.api_key } : {}),
-            ...(useCodexLb && codexLb.model ? { model: codexLb.model } : {})
-        });
+        const suppliedTarget = opts.desktopBridgeTarget
+            ? fixtureDesktopBridgeTarget(opts.desktopBridgeTarget)
+            : null;
+        const target = suppliedTarget || await resolveDesktopBridgeImagegenTarget({
+            explicitModel: input.model
+                || process.env.OPENAI_STRUCTURED_OUTPUT_MODEL
+                || process.env.SKS_IMAGEGEN_RESPONSES_MODEL
+                || null,
+            ...(opts.home ? { home: opts.home } : {}),
+            ...(opts.env ? { env: opts.env } : {}),
+            ...(opts.desktopBridgeStatus !== undefined ? { desktopBridgeStatus: opts.desktopBridgeStatus } : {}),
+            ...(opts.desktopBridgeStatusImpl ? { desktopBridgeStatusImpl: opts.desktopBridgeStatusImpl } : {})
+        }).catch(() => null);
+        if (!target || target.blocker || !target.endpoint || !target.model) {
+            const reason = target?.blocker || 'desktop_bridge_status_unavailable';
+            providerResult = {
+                ok: false,
+                status: 'blocked',
+                provider: 'desktop_bridge_structured_extractor',
+                parsed_json: null,
+                blocker: structuredOutputBlocker(reason, DESKTOP_BRIDGE_IMAGEGEN_RECOVERY_GUIDANCE),
+                fixture: target?.status_source === 'injected_fixture'
+            };
+        }
+        else {
+            providerResult = await runDesktopBridgeStructuredOutput({
+                target,
+                prompt,
+                schemaName: 'image_ux_issue_ledger',
+                jsonSchema,
+                imagePath: path.resolve(input.root, input.generatedImagePath)
+            });
+        }
     }
     if (!providerResult.ok || !providerResult.parsed_json) {
         return {
@@ -95,6 +120,7 @@ export async function extractRealCallouts(input) {
             generated_image_sha256: generated.sha256,
             parsed_json_present: false,
             validation_status: 'blocked',
+            ...(providerResult.fixture ? { fake_adapter: true, source: 'mock_fixture' } : {}),
             issue_ledger: buildIssueLedgerFromGeneratedCallouts({
                 schema: 'sks.image-ux-generated-review-ledger.v2',
                 generated_review_images: [{ ...generated, callout_extraction_status: 'pending', callouts: [] }],
@@ -123,9 +149,113 @@ export async function extractRealCallouts(input) {
         parsed_json_present: true,
         validation_status: ledger.validation.ok ? 'valid' : 'blocked',
         issue_ledger: ledger,
+        ...(providerResult.fixture ? { fake_adapter: true, source: 'mock_fixture' } : {}),
         blocker: ledger.issues.length ? null : structuredOutputBlocker('callout_extraction_schema_failed', 'Generated image did not yield visible callouts.')
     };
 }
+async function runDesktopBridgeStructuredOutput(request) {
+    const imageBytes = await fsp.readFile(request.imagePath);
+    const imageUrl = `data:${mimeForPath(request.imagePath)};base64,${imageBytes.toString('base64')}`;
+    const fixture = request.target.status_source === 'injected_fixture'
+        || request.target.live_evidence_allowed !== true;
+    try {
+        const response = await fetch(request.target.endpoint, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                'x-sks-model': request.target.model
+            },
+            body: JSON.stringify({
+                model: request.target.model,
+                input: [{
+                        role: 'user',
+                        content: [
+                            { type: 'input_text', text: request.prompt },
+                            { type: 'input_image', image_url: imageUrl }
+                        ]
+                    }],
+                text: { format: strictJsonSchemaFormat(request.schemaName, request.jsonSchema) }
+            })
+        });
+        const text = await response.text();
+        if (!response.ok) {
+            return bridgeStructuredOutputBlocked('desktop_bridge_structured_output_api_error', text, fixture);
+        }
+        const payload = parseStructuredOutputBody(text);
+        if (!payload)
+            return bridgeStructuredOutputBlocked('json_parse_failed', 'Desktop Bridge returned no readable JSON.', fixture);
+        const parsed = payload.output_parsed || parseStructuredOutputPayload(payload);
+        if (!parsed || typeof parsed !== 'object') {
+            return bridgeStructuredOutputBlocked('json_parse_failed', 'Desktop Bridge output did not contain parsed JSON.', fixture);
+        }
+        const validation = validateStructuredOutput(parsed, strictJsonSchemaFormat(request.schemaName, request.jsonSchema).schema);
+        return {
+            ok: validation.ok,
+            status: validation.ok ? 'parsed' : 'blocked',
+            provider: fixture ? 'desktop_bridge_fixture_structured_extractor' : 'desktop_bridge_structured_extractor',
+            parsed_json: validation.ok ? parsed : null,
+            blocker: validation.ok
+                ? null
+                : structuredOutputBlocker('schema_validation_failed', validation.issues.join(', ')),
+            fixture
+        };
+    }
+    catch (error) {
+        return bridgeStructuredOutputBlocked('desktop_bridge_structured_output_api_error', error instanceof Error ? error.message : String(error), fixture);
+    }
+}
+function bridgeStructuredOutputBlocked(reason, detail, fixture) {
+    return {
+        ok: false,
+        status: 'blocked',
+        provider: fixture ? 'desktop_bridge_fixture_structured_extractor' : 'desktop_bridge_structured_extractor',
+        parsed_json: null,
+        blocker: structuredOutputBlocker(reason, String(detail || '').slice(0, 2000)),
+        fixture
+    };
+}
+function fixtureDesktopBridgeTarget(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    return {
+        ...value,
+        status_source: 'injected_fixture',
+        live_evidence_allowed: false
+    };
+}
+function parseStructuredOutputBody(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return parseResponsesSsePayload(text);
+    }
+}
+function parseStructuredOutputPayload(payload) {
+    const output = Array.isArray(payload.output) ? payload.output : [];
+    for (const item of output) {
+        const content = Array.isArray(item?.content) ? item.content : [];
+        for (const part of content) {
+            if (part?.parsed)
+                return part.parsed;
+            if (typeof part?.text === 'string') {
+                try {
+                    return JSON.parse(part.text);
+                }
+                catch { }
+            }
+        }
+    }
+    return null;
+}
+function mimeForPath(file) {
+    const ext = path.extname(file).toLowerCase();
+    if (ext === '.jpg' || ext === '.jpeg')
+        return 'image/jpeg';
+    if (ext === '.webp')
+        return 'image/webp';
+    return 'image/png';
+}
 export function buildRealCalloutExtractionPrompt(input) {
     const source = input.sourceScreenshot || {};
     return [

package/dist/core/imagegen/desktop-bridge-imagegen-target.js

@@ -0,0 +1,77 @@
+import { desktopBridgeStatusV3 } from '../codex-lb/desktop-controller-v3.js';
+export const DESKTOP_BRIDGE_IMAGEGEN_TARGET_SCHEMA = 'sks.desktop-bridge-imagegen-target.v1';
+export const DESKTOP_BRIDGE_IMAGEGEN_RECOVERY_GUIDANCE = 'Run `sks bridge status --json` to inspect Desktop Bridge provider readiness.';
+export async function resolveDesktopBridgeImagegenTarget(opts = {}) {
+    const env = opts.env || process.env;
+    const injected = opts.desktopBridgeStatus !== undefined || opts.desktopBridgeStatusImpl !== undefined;
+    const status = opts.desktopBridgeStatus !== undefined
+        ? opts.desktopBridgeStatus
+        : await (opts.desktopBridgeStatusImpl || desktopBridgeStatusV3)({
+            ...(opts.home ? { home: opts.home } : {}),
+            env
+        }).catch(() => null);
+    const model = String(opts.explicitModel ?? env.SKS_IMAGEGEN_RESPONSES_MODEL ?? '').trim() || null;
+    const selected = status?.schema === 'sks.desktop-bridge-status.v3'
+        && status.management?.managed === true;
+    const loopbackOrigin = verifiedLoopbackOrigin(status);
+    const policy = status?.routing?.policy || null;
+    const route = model && policy?.fallback === 'none'
+        ? policy.model_routes?.[model] || null
+        : null;
+    const provider = route ? status?.providers?.[route.provider_id] || null : null;
+    const providerImagegen = provider?.capabilities?.capabilities?.image_generation || null;
+    const blocker = !status || status.schema !== 'sks.desktop-bridge-status.v3'
+        ? 'desktop_bridge_status_unavailable'
+        : !selected
+            ? 'desktop_bridge_not_managed'
+            : status.service?.running !== true || status.service?.state !== 'ready'
+                ? 'desktop_bridge_not_running'
+                : !loopbackOrigin
+                    ? 'desktop_bridge_loopback_unverified'
+                    : status.readiness?.bridge_ready !== true || status.catalog_sync?.state !== 'verified'
+                        ? status.readiness?.blockers?.[0] || status.catalog_sync?.blockers?.[0] || 'desktop_bridge_state_unverified'
+                        : !model
+                            ? 'desktop_bridge_imagegen_model_missing'
+                            : !policy || policy.fallback !== 'none' || !route
+                                ? 'catalog_model_route_missing'
+                                : provider?.enabled !== true
+                                    ? 'bridge_route_provider_disabled'
+                                    : provider.credential?.state !== 'ready'
+                                        ? provider.credential?.blockers?.[0] || 'bridge_route_provider_credential_unverified'
+                                        : providerImagegen?.state !== 'verified'
+                                            ? providerImagegen?.blockers?.[0] || 'bridge_route_imagegen_capability_unverified'
+                                            : null;
+    const bridgeVerified = blocker === null;
+    return {
+        schema: DESKTOP_BRIDGE_IMAGEGEN_TARGET_SCHEMA,
+        selected,
+        bridge_verified: bridgeVerified,
+        endpoint: bridgeVerified ? `${loopbackOrigin}/backend-api/codex/responses` : null,
+        model,
+        model_source: model ? 'explicit' : null,
+        route: route || null,
+        provider_id: route?.provider_id || null,
+        status_source: injected ? 'injected_fixture' : 'runtime',
+        live_evidence_allowed: bridgeVerified && !injected,
+        blocker,
+        setup_guidance: DESKTOP_BRIDGE_IMAGEGEN_RECOVERY_GUIDANCE
+    };
+}
+function verifiedLoopbackOrigin(status) {
+    const raw = String(status?.service?.loopback_origin || '').trim();
+    if (!raw)
+        return null;
+    try {
+        const parsed = new URL(raw);
+        const loopback = parsed.hostname === '127.0.0.1'
+            || parsed.hostname === '::1'
+            || parsed.hostname === '[::1]';
+        if (parsed.protocol !== 'http:' || !loopback || parsed.username || parsed.password
+            || parsed.pathname !== '/' || parsed.search || parsed.hash || !parsed.port)
+            return null;
+        return parsed.origin;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/core/imagegen/imagegen-capability.js

@@ -1,11 +1,7 @@
-import os from 'node:os';
-import path from 'node:path';
-import { loadCodexLbEnv, parseShellEnvValue } from '../codex-lb/codex-lb-env.js';
-import { CODEX_LB_ROUTING_TRUTH_RECEIPT, codexLbRoutingTruthIsActive, readCodexLbRoutingTruthReceipt } from '../codex-lb/routing-truth.js';
-import { nowIso, readText, runProcess, which } from '../fsx.js';
+import { desktopBridgeStatusV3 } from '../codex-lb/desktop-controller-v3.js';
+import { nowIso, runProcess, which } from '../fsx.js';
 import { redactSecrets, redactString } from '../secret-redaction.js';
 import { evaluateImagegenAuthReadiness } from './imagegen-auth-readiness.js';
-import { escapeRegExp } from '../text/regex.js';
 export async function detectImagegenCapability(opts = {}) {
     const codexBin = opts.codexBin || await which('codex').catch(() => null);
     const codexApp = await detectCodexAppImagegen(codexBin, opts);
@@ -97,130 +93,57 @@ export async function detectImagegenCapability(opts = {}) {
     };
 }
 async function detectCodexLbImagegenAuth(opts = {}, env = process.env) {
-    const home = opts.home || env.HOME || process.env.HOME || os.homedir();
-    const codexHome = opts.codexHome || env.CODEX_HOME || path.join(home, '.codex');
-    const configPath = opts.configPath || path.join(codexHome, 'config.toml');
-    const configText = typeof opts.configText === 'string'
-        ? opts.configText
-        : await readText(configPath, '').catch(() => '');
-    const block = tomlTableBlock(configText, 'model_providers.codex-lb');
-    const selected = opts.codexLbSelected === true || topLevelTomlString(configText, 'model_provider') === 'codex-lb';
-    const providerConfigured = Boolean(block);
-    const requiresOpenAiAuth = tomlBoolean(block, 'requires_openai_auth');
-    const bearerEnvKey = tomlString(block, 'env_key');
-    const gatewayHeaderEnvKey = tomlEnvHttpHeader(block, 'X-Codex-LB-API-Key');
-    const envKey = bearerEnvKey || gatewayHeaderEnvKey;
-    const cliContract = providerConfigured
-        && tomlString(block, 'name') === 'codex-lb'
-        && tomlString(block, 'wire_api') === 'responses'
-        && bearerEnvKey === 'CODEX_LB_API_KEY'
-        && !gatewayHeaderEnvKey
-        && requiresOpenAiAuth === false;
-    const baseUrl = tomlString(block, 'base_url') || String(env.CODEX_LB_BASE_URL || '').trim();
-    const envPath = opts.codexLbEnvPath || path.join(codexHome, 'sks-codex-lb.env');
-    const injectedEnvText = typeof opts.codexLbEnvText === 'string' ? opts.codexLbEnvText : null;
-    const keyFromInjectedFile = injectedEnvText !== null && envKey ? parseShellEnvValue(injectedEnvText, envKey) : '';
-    const loaded = injectedEnvText === null
-        ? await loadCodexLbEnv({
-            home,
-            processEnv: {},
-            envPath,
-            metadataPath: path.join(codexHome, 'sks-codex-lb.json')
-        }).catch(() => null)
-        : null;
-    const apiKeyPresent = Boolean(opts.codexLbApiKey || keyFromInjectedFile || loaded?.secret_api_key);
-    const apiKeySource = opts.codexLbApiKey
-        ? 'option'
-        : keyFromInjectedFile ? 'env-file' : loaded?.api_key?.source || null;
-    const blocker = codexLbAuthBlocker({
-        selected,
-        providerConfigured,
-        requiresOpenAiAuth,
-        envKey,
-        baseUrl,
-        apiKeyPresent,
-        cliContract
-    });
-    const routingTruthReceiptPath = opts.codexLbRoutingTruthReceiptPath
-        || path.join(codexHome, CODEX_LB_ROUTING_TRUTH_RECEIPT);
-    const routingTruth = await readCodexLbRoutingTruthReceipt({
-        receiptPath: routingTruthReceiptPath
+    const status = opts.desktopBridgeStatus || await (opts.desktopBridgeStatusImpl || desktopBridgeStatusV3)({
+        home: opts.home || env.HOME,
+        env
     }).catch(() => null);
-    const configuredHost = publicUrlHost(baseUrl);
-    const routingAuthTransport = 'authorization-bearer';
-    const routingTruthContextMatches = routingTruth?.selected === selected
-        && routingTruth?.configured_host === configuredHost
-        && routingTruth?.auth_transport === routingAuthTransport;
-    const routingActive = routingTruthContextMatches
-        && codexLbRoutingTruthIsActive(routingTruth);
+    const provider = status?.providers?.['codex-lb'] || null;
+    const policy = status?.routing?.policy || null;
+    const modelRoutes = Object.values(policy?.model_routes || {});
+    const selected = provider?.enabled === true && (policy?.default_provider_id === 'codex-lb'
+        || modelRoutes.some((route) => route?.provider_id === 'codex-lb'));
+    const credentialReady = provider?.credential?.state === 'ready';
+    const endpointConfigured = provider?.endpoint?.configured === true;
+    const capabilityEvidence = provider?.capabilities?.capabilities?.image_generation || null;
+    const capabilityReady = capabilityEvidence?.state === 'verified';
+    const blocker = !status
+        ? 'desktop_bridge_status_unavailable'
+        : !provider
+            ? 'codex_lb_provider_status_missing'
+            : !provider.enabled
+                ? 'codex_lb_provider_disabled'
+                : !credentialReady
+                    ? provider.credential?.blockers?.[0] || `codex_lb_credential_${provider.credential?.state || 'unknown'}`
+                    : !endpointConfigured
+                        ? 'codex_lb_endpoint_missing'
+                        : !selected
+                            ? 'codex_lb_route_inactive'
+                            : !capabilityReady
+                                ? capabilityEvidence?.blockers?.[0] || `codex_lb_imagegen_capability_${capabilityEvidence?.state || 'unverified'}`
+                                : null;
     return {
         available: blocker === null,
         selected,
-        cli_contract: cliContract,
-        provider_configured: providerConfigured,
-        requires_openai_auth: requiresOpenAiAuth,
-        openai_auth_disabled: requiresOpenAiAuth === false,
-        env_key: envKey || null,
-        base_url: baseUrl || null,
-        env_path: envPath,
+        cli_contract: provider?.endpoint?.auth_transport === 'authorization-bearer',
+        provider_configured: Boolean(provider),
+        requires_openai_auth: null,
+        openai_auth_disabled: null,
+        env_key: null,
+        base_url: provider?.endpoint?.origin_redacted || null,
+        env_path: null,
         api_key: {
-            present: apiKeyPresent,
-            source: apiKeySource,
+            present: credentialReady,
+            source: provider?.credential?.source || null,
             redacted: true
         },
-        routing_active: routingActive,
-        routing_truth: routingTruth,
-        routing_truth_receipt_path: routingTruthReceiptPath,
-        routing_blocker: codexLbRoutingBlocker({
-            selected,
-            configuredHost,
-            routingTruth,
-            expectedAuthTransport: routingAuthTransport,
-            routingTruthContextMatches,
-            routingActive
-        }),
+        routing_active: selected,
+        routing_blocker: selected ? null : 'codex_lb_route_inactive',
+        capability_evidence: capabilityEvidence,
+        provider_capability_summary: provider?.capabilities || null,
+        bridge_status_checked_at: status?.checked_at || null,
         blocker
     };
 }
-function codexLbRoutingBlocker(state) {
-    if (!state.selected)
-        return 'codex_lb_not_selected';
-    if (!state.routingTruth)
-        return 'codex_lb_routing_truth_receipt_missing';
-    if (state.routingTruth.selected !== true)
-        return 'codex_lb_routing_truth_selection_mismatch';
-    if (state.routingTruth.configured_host !== state.configuredHost)
-        return 'codex_lb_routing_truth_host_mismatch';
-    if (state.routingTruth.auth_transport !== state.expectedAuthTransport)
-        return 'codex_lb_routing_truth_auth_transport_mismatch';
-    if (!state.routingTruthContextMatches || !state.routingActive) {
-        return state.routingTruth.blockers?.[0] || 'codex_lb_routing_truth_unverified';
-    }
-    return null;
-}
-function codexLbAuthBlocker(state) {
-    if (!state.selected && !state.cliContract)
-        return 'codex_lb_not_selected';
-    if (!state.providerConfigured)
-        return 'codex_lb_provider_missing';
-    if (state.cliContract) {
-        if (!state.apiKeyPresent)
-            return 'codex_lb_api_key_missing';
-        if (!state.baseUrl)
-            return 'codex_lb_base_url_missing';
-        return null;
-    }
-    if (state.requiresOpenAiAuth !== true) {
-        return state.requiresOpenAiAuth === false ? 'codex_lb_legacy_openai_auth_disabled' : 'codex_lb_requires_openai_auth_missing';
-    }
-    if (state.envKey !== 'CODEX_LB_API_KEY')
-        return 'codex_lb_env_key_missing_or_unsupported';
-    if (!state.baseUrl)
-        return 'codex_lb_base_url_missing';
-    if (!state.apiKeyPresent)
-        return 'codex_lb_api_key_missing';
-    return null;
-}
 async function detectCodexAppImagegen(codexBin, opts = {}) {
     if (opts.codexAppAvailable === true || process.env.SKS_CODEX_APP_IMAGEGEN_AVAILABLE === '1') {
         return { available: true, detector: 'env_or_option', blocker: null, raw: null };
@@ -323,34 +246,3 @@ function boolish(value) {
         return false;
     return null;
 }
-function publicUrlHost(value) {
-    try {
-        return typeof value === 'string' && value ? new URL(value).host : null;
-    }
-    catch {
-        return null;
-    }
-}
-function topLevelTomlString(text = '', key = '') {
-    const topLevel = String(text || '').split(/\n\s*\[/)[0] || '';
-    return tomlString(topLevel, key);
-}
-function tomlTableBlock(text = '', table = '') {
-    const re = new RegExp(`(^|\\n)\\[${escapeRegExp(table)}\\]([\\s\\S]*?)(?=\\n\\[[^\\]]+\\]|\\s*$)`);
-    return String(text || '').match(re)?.[2] || '';
-}
-function tomlString(text = '', key = '') {
-    const re = new RegExp(`(^|\\n)\\s*${escapeRegExp(key)}\\s*=\\s*"([^"]*)"\\s*(?:#.*)?(?=\\n|$)`);
-    return String(text || '').match(re)?.[2] || '';
-}
-function tomlEnvHttpHeader(text = '', header = '') {
-    const inline = String(text || '').match(/(?:^|\n)\s*env_http_headers\s*=\s*\{([^}]*)\}/)?.[1] || '';
-    return inline.match(new RegExp(`"${escapeRegExp(header)}"\\s*=\\s*"([^"]+)"`))?.[1] || '';
-}
-function tomlBoolean(text = '', key = '') {
-    const re = new RegExp(`(^|\\n)\\s*${escapeRegExp(key)}\\s*=\\s*(true|false)\\s*(?:#.*)?(?=\\n|$)`, 'i');
-    const raw = String(text || '').match(re)?.[2];
-    if (!raw)
-        return null;
-    return raw.toLowerCase() === 'true';
-}

package/dist/core/init/skills/filesystem.js

@@ -0,0 +1,89 @@
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import { inspectConfinedPath } from '../../managed-path-safety.js';
+import { sha256 } from '../../fsx.js';
+import { SKS_SKILL_MANIFEST_FILE, canonicalSkillNameFromValue } from './inventory.js';
+export async function listSkillDirs(targetDir, opts = {}) {
+    const boundary = rootFromSkillsDir(targetDir);
+    let rootInspection;
+    try {
+        rootInspection = await inspectConfinedPath(boundary, targetDir);
+    }
+    catch (error) {
+        if (nodeErrorCode(error) === 'ENOENT')
+            return [];
+        throw error;
+    }
+    if (!rootInspection.exists)
+        return [];
+    if (rootInspection.leafSymlink || !rootInspection.stat?.isDirectory()) {
+        throw new Error(`skill_target_not_safe_directory:${targetDir}`);
+    }
+    const rows = await fsp.readdir(targetDir, { withFileTypes: true });
+    const out = [];
+    for (const row of rows) {
+        const dir = path.join(targetDir, row.name);
+        const directoryCanonical = canonicalSkillNameFromValue(row.name);
+        if (row.isSymbolicLink() || !row.isDirectory()) {
+            if (opts.includeUnsafeEntries) {
+                out.push({
+                    name: row.name,
+                    dir,
+                    skillMdPath: null,
+                    text: '',
+                    canonical: directoryCanonical,
+                    declaredCanonical: '',
+                    directoryCanonical,
+                    hash: '',
+                    unsafeEntry: row.isSymbolicLink() ? 'symlink' : 'non-directory'
+                });
+            }
+            continue;
+        }
+        const skillMdPath = path.join(dir, 'SKILL.md');
+        const inspected = await inspectConfinedPath(boundary, skillMdPath);
+        if (!inspected.exists || inspected.leafSymlink || !inspected.stat?.isFile()) {
+            if (opts.includeUnsafeEntries) {
+                out.push({
+                    name: row.name,
+                    dir,
+                    skillMdPath,
+                    text: '',
+                    canonical: directoryCanonical,
+                    declaredCanonical: '',
+                    directoryCanonical,
+                    hash: '',
+                    unsafeEntry: inspected.leafSymlink ? 'skill-file-symlink' : 'missing-or-non-file-skill'
+                });
+            }
+            continue;
+        }
+        const text = await fsp.readFile(skillMdPath, 'utf8');
+        const displayName = /^name:\s*(.+)\s*$/m.exec(text)?.[1] || row.name;
+        const declaredCanonical = canonicalSkillNameFromValue(displayName);
+        out.push({
+            name: row.name,
+            dir,
+            skillMdPath,
+            text,
+            canonical: declaredCanonical,
+            declaredCanonical,
+            directoryCanonical,
+            hash: sha256(text)
+        });
+    }
+    return out;
+}
+export function rootFromSkillsDir(targetDir) {
+    const normalized = path.resolve(targetDir);
+    if (path.basename(normalized) === 'skills' && path.basename(path.dirname(normalized)) === '.agents') {
+        return path.dirname(path.dirname(normalized));
+    }
+    return path.dirname(path.dirname(normalized));
+}
+export async function pruneProjectGeneratedManifest(targetDir) {
+    await fsp.rm(path.join(targetDir, SKS_SKILL_MANIFEST_FILE), { force: true }).catch(() => undefined);
+}
+function nodeErrorCode(error) {
+    return String(error?.code || '');
+}