apcore-toolkit 0.1.0 → 0.3.0

package/dist/output/yaml-writer.js

@@ -2,9 +2,14 @@ import yaml from 'js-yaml';
 import { writeFileSync, mkdirSync, existsSync } from 'node:fs';
 import { resolve, join } from 'node:path';
 import { annotationsToDict } from '../serializers.js';
+import { createWriteResult } from './types.js';
+import { WriteError } from './errors.js';
+import { YAMLVerifier, runVerifierChain } from './verifiers.js';
 export class YAMLWriter {
     write(modules, outputDir, options) {
         const dryRun = options?.dryRun ?? false;
+        const shouldVerify = options?.verify ?? false;
+        const verifiers = options?.verifiers ?? [];
         if (modules.length === 0) {
             return [];
         }
@@ -16,29 +21,49 @@ export class YAMLWriter {
         const timestamp = new Date().toISOString();
         for (const module of modules) {
             const bindingData = this._buildBinding(module);
-            results.push(bindingData);
-            if (!dryRun) {
-                let safeId = module.moduleId.replace(/[^a-zA-Z0-9._-]/g, '_');
-                safeId = safeId.replace(/\.{2,}/g, '_');
-                const filename = `${safeId}.binding.yaml`;
-                const filePath = resolve(join(outputPath, filename));
-                // Path traversal protection
-                if (!filePath.startsWith(outputPath)) {
-                    console.warn('Skipping file outside output directory: %s', filePath);
-                    continue;
+            if (dryRun) {
+                results.push(createWriteResult(module.moduleId, null));
+                continue;
+            }
+            let safeId = module.moduleId.replace(/[^a-zA-Z0-9._-]/g, '_');
+            safeId = safeId.replace(/\.{2,}/g, '_');
+            const filename = `${safeId}.binding.yaml`;
+            const filePath = resolve(join(outputPath, filename));
+            // Path traversal protection
+            if (!filePath.startsWith(outputPath)) {
+                console.warn('Skipping file outside output directory: %s', filePath);
+                continue;
+            }
+            if (existsSync(filePath)) {
+                console.warn('Overwriting existing file: %s', filePath);
+            }
+            const header = `# Auto-generated by apcore-toolkit scanner\n` +
+                `# Generated: ${timestamp}\n` +
+                `# Do not edit manually unless you intend to customize schemas.\n\n`;
+            const yamlContent = yaml.dump(bindingData, {
+                flowLevel: -1,
+                sortKeys: false,
+            });
+            try {
+                writeFileSync(filePath, header + yamlContent, 'utf-8');
+            }
+            catch (err) {
+                throw new WriteError(filePath, err);
+            }
+            let result = createWriteResult(module.moduleId, filePath);
+            if (shouldVerify) {
+                const builtinResult = new YAMLVerifier().verify(filePath, module.moduleId);
+                if (!builtinResult.ok) {
+                    result = createWriteResult(module.moduleId, filePath, false, builtinResult.error ?? null);
                 }
-                if (existsSync(filePath)) {
-                    console.warn('Overwriting existing file: %s', filePath);
+            }
+            if (result.verified && verifiers.length > 0) {
+                const vResult = runVerifierChain(verifiers, filePath, module.moduleId);
+                if (!vResult.ok) {
+                    result = createWriteResult(module.moduleId, filePath, false, vResult.error ?? null);
                 }
-                const header = `# Auto-generated by apcore-toolkit scanner\n` +
-                    `# Generated: ${timestamp}\n` +
-                    `# Do not edit manually unless you intend to customize schemas.\n\n`;
-                const yamlContent = yaml.dump(bindingData, {
-                    flowLevel: -1,
-                    sortKeys: false,
-                });
-                writeFileSync(filePath, header + yamlContent, 'utf-8');
             }
+            results.push(result);
         }
         return results;
     }
@@ -56,9 +81,9 @@ export class YAMLWriter {
                     examples: module.examples.length > 0
                         ? module.examples.map((e) => ({ ...e }))
                         : [],
-                    metadata: { ...module.metadata },
-                    input_schema: { ...module.inputSchema },
-                    output_schema: { ...module.outputSchema },
+                    metadata: structuredClone(module.metadata),
+                    input_schema: structuredClone(module.inputSchema),
+                    output_schema: structuredClone(module.outputSchema),
                 },
             ],
         };

package/dist/output/yaml-writer.js.map

@@ -1 +1 @@
-{"version":3,"file":"yaml-writer.js","sourceRoot":"","sources":["../../src/output/yaml-writer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"yaml-writer.js","sourceRoot":"","sources":["../../src/output/yaml-writer.ts"],"names":[],"mappings":"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"}

package/dist/resolve-target.d.ts

@@ -4,6 +4,12 @@
  * Target format: `"module/path:exportName"`.
  * The LAST `:` is used as the separator so that Node.js built-in prefixes
  * like `node:path` are supported (e.g. `"node:path:join"`).
+ *
+ * @param target - The target string in "module:export" format.
+ * @param allowedPrefixes - Optional list of allowed directory prefixes for
+ *   absolute/relative paths. If provided, file-path imports must resolve
+ *   under one of these directories. Package-name imports (no leading `.` or `/`)
+ *   are always allowed.
  */
-export declare function resolveTarget(target: string): Promise<unknown>;
+export declare function resolveTarget(target: string, allowedPrefixes?: string[]): Promise<unknown>;
 //# sourceMappingURL=resolve-target.d.ts.map

package/dist/resolve-target.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-target.d.ts","sourceRoot":"","sources":["../src/resolve-target.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CA0BpE"}
+{"version":3,"file":"resolve-target.d.ts","sourceRoot":"","sources":["../src/resolve-target.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,EACd,eAAe,CAAC,EAAE,MAAM,EAAE,GACzB,OAAO,CAAC,OAAO,CAAC,CAwClB"}

package/dist/resolve-target.js

@@ -1,17 +1,33 @@
+import { resolve, isAbsolute } from 'node:path';
 /**
  * Dynamically imports a module and resolves a named export.
  *
  * Target format: `"module/path:exportName"`.
  * The LAST `:` is used as the separator so that Node.js built-in prefixes
  * like `node:path` are supported (e.g. `"node:path:join"`).
+ *
+ * @param target - The target string in "module:export" format.
+ * @param allowedPrefixes - Optional list of allowed directory prefixes for
+ *   absolute/relative paths. If provided, file-path imports must resolve
+ *   under one of these directories. Package-name imports (no leading `.` or `/`)
+ *   are always allowed.
  */
-export async function resolveTarget(target) {
+export async function resolveTarget(target, allowedPrefixes) {
     const lastColon = target.lastIndexOf(":");
     if (lastColon === -1) {
         throw new Error(`Invalid target format: "${target}". Expected "module/path:exportName".`);
     }
     const modulePath = target.slice(0, lastColon);
     const exportName = target.slice(lastColon + 1);
+    // Validate file-path imports against allowedPrefixes
+    const isFilePath = modulePath.startsWith('.') || isAbsolute(modulePath);
+    if (isFilePath && allowedPrefixes != null && allowedPrefixes.length > 0) {
+        const resolved = resolve(modulePath);
+        const allowed = allowedPrefixes.some((prefix) => resolved.startsWith(resolve(prefix)));
+        if (!allowed) {
+            throw new Error(`Import path "${modulePath}" is not under any allowed prefix: ${allowedPrefixes.join(', ')}`);
+        }
+    }
     let mod;
     try {
         mod = (await import(modulePath));

package/dist/resolve-target.js.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-target.js","sourceRoot":"","sources":["../src/resolve-target.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,MAAc;IAChD,MAAM,SAAS,GAAG,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAC1C,IAAI,SAAS,KAAK,CAAC,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CACb,2BAA2B,MAAM,uCAAuC,CACzE,CAAC;IACJ,CAAC;IAED,MAAM,UAAU,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;IAC9C,MAAM,UAAU,GAAG,MAAM,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC;IAE/C,IAAI,GAA4B,CAAC;IACjC,IAAI,CAAC;QACH,GAAG,GAAG,CAAC,MAAM,MAAM,CAAC,UAAU,CAAC,CAA4B,CAAC;IAC9D,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,MAAM,IAAI,KAAK,CAAC,4BAA4B,UAAU,MAAM,OAAO,EAAE,CAAC,CAAC;IACzE,CAAC;IAED,IAAI,GAAG,CAAC,UAAU,CAAC,KAAK,SAAS,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CACb,WAAW,UAAU,0BAA0B,UAAU,IAAI,CAC9D,CAAC;IACJ,CAAC;IAED,OAAO,GAAG,CAAC,UAAU,CAAC,CAAC;AACzB,CAAC"}
+{"version":3,"file":"resolve-target.js","sourceRoot":"","sources":["../src/resolve-target.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAEhD;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,MAAc,EACd,eAA0B;IAE1B,MAAM,SAAS,GAAG,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAC1C,IAAI,SAAS,KAAK,CAAC,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CACb,2BAA2B,MAAM,uCAAuC,CACzE,CAAC;IACJ,CAAC;IAED,MAAM,UAAU,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;IAC9C,MAAM,UAAU,GAAG,MAAM,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC;IAE/C,qDAAqD;IACrD,MAAM,UAAU,GAAG,UAAU,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,UAAU,CAAC,UAAU,CAAC,CAAC;IACxE,IAAI,UAAU,IAAI,eAAe,IAAI,IAAI,IAAI,eAAe,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxE,MAAM,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;QACrC,MAAM,OAAO,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAC9C,QAAQ,CAAC,UAAU,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CACrC,CAAC;QACF,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CACb,gBAAgB,UAAU,sCAAsC,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC7F,CAAC;QACJ,CAAC;IACH,CAAC;IAED,IAAI,GAA4B,CAAC;IACjC,IAAI,CAAC;QACH,GAAG,GAAG,CAAC,MAAM,MAAM,CAAC,UAAU,CAAC,CAA4B,CAAC;IAC9D,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,MAAM,IAAI,KAAK,CAAC,4BAA4B,UAAU,MAAM,OAAO,EAAE,CAAC,CAAC;IACzE,CAAC;IAED,IAAI,GAAG,CAAC,UAAU,CAAC,KAAK,SAAS,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CACb,WAAW,UAAU,0BAA0B,UAAU,IAAI,CAC9D,CAAC;IACJ,CAAC;IAED,OAAO,GAAG,CAAC,UAAU,CAAC,CAAC;AACzB,CAAC"}

package/dist/scanner.d.ts

@@ -3,6 +3,11 @@ import type { ScannedModule } from './types.js';
 export declare abstract class BaseScanner {
     abstract scan(...args: unknown[]): ScannedModule[] | Promise<ScannedModule[]>;
     abstract getSourceName(): string;
+    extractDocstring(func: unknown): {
+        description: string | null;
+        documentation: string | null;
+        params: Record<string, string>;
+    };
     filterModules(modules: ScannedModule[], options?: {
         include?: string;
         exclude?: string;

package/dist/scanner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scanner.d.ts","sourceRoot":"","sources":["../src/scanner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAEnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAGhD,8BAAsB,WAAW;IAC/B,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,aAAa,EAAE,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAC7E,QAAQ,CAAC,aAAa,IAAI,MAAM;IAEhC,aAAa,CACX,OAAO,EAAE,aAAa,EAAE,EACxB,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAC/C,aAAa,EAAE;IAgBlB,MAAM,CAAC,0BAA0B,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB;IAgBpE,cAAc,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,aAAa,EAAE;CA2B1D"}
+{"version":3,"file":"scanner.d.ts","sourceRoot":"","sources":["../src/scanner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAEnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAYhD,8BAAsB,WAAW;IAC/B,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,aAAa,EAAE,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAC7E,QAAQ,CAAC,aAAa,IAAI,MAAM;IAEhC,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG;QAC/B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;QAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KAChC;IAwCD,aAAa,CACX,OAAO,EAAE,aAAa,EAAE,EACxB,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAC/C,aAAa,EAAE;IAgBlB,MAAM,CAAC,0BAA0B,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB;IAgBpE,cAAc,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,aAAa,EAAE;CA2B1D"}

package/dist/scanner.js

@@ -1,22 +1,67 @@
 import { DEFAULT_ANNOTATIONS } from 'apcore-js';
 import { cloneModule } from './types.js';
+function safeRegExp(pattern) {
+    try {
+        return new RegExp(pattern);
+    }
+    catch {
+        // If the pattern is invalid regex, treat it as a literal string
+        return new RegExp(pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+    }
+}
 export class BaseScanner {
+    extractDocstring(func) {
+        if (func == null || typeof func !== 'function') {
+            return { description: null, documentation: null, params: {} };
+        }
+        // Extract JSDoc-style documentation from function's toString representation
+        const source = func.toString();
+        const jsdocMatch = source.match(/\/\*\*([\s\S]*?)\*\//);
+        if (!jsdocMatch) {
+            return { description: null, documentation: null, params: {} };
+        }
+        const raw = jsdocMatch[1];
+        const lines = raw
+            .split('\n')
+            .map((l) => l.replace(/^\s*\*\s?/, '').trim())
+            .filter((l) => l.length > 0);
+        const descLines = [];
+        const params = {};
+        let hitTag = false;
+        for (const line of lines) {
+            if (line.startsWith('@param')) {
+                hitTag = true;
+                const m = line.match(/@param\s+\{?\w*\}?\s*(\w+)\s*(.*)/);
+                if (m)
+                    params[m[1]] = m[2].replace(/^-\s*/, '').trim();
+            }
+            else if (line.startsWith('@')) {
+                hitTag = true;
+            }
+            else if (!hitTag) {
+                descLines.push(line);
+            }
+        }
+        const description = descLines.length > 0 ? descLines[0] : null;
+        const documentation = descLines.length > 1 ? descLines.join('\n') : null;
+        return { description, documentation, params };
+    }
     filterModules(modules, options) {
         let result = modules;
         if (options?.include != null) {
-            const include = options.include;
-            result = result.filter((m) => new RegExp(include).test(m.moduleId));
+            const re = safeRegExp(options.include);
+            result = result.filter((m) => re.test(m.moduleId));
         }
         if (options?.exclude != null) {
-            const exclude = options.exclude;
-            result = result.filter((m) => !new RegExp(exclude).test(m.moduleId));
+            const re = safeRegExp(options.exclude);
+            result = result.filter((m) => !re.test(m.moduleId));
         }
         return result;
     }
     static inferAnnotationsFromMethod(method) {
         const upper = method.toUpperCase();
         if (upper === 'GET') {
-            return { ...DEFAULT_ANNOTATIONS, readonly: true };
+            return { ...DEFAULT_ANNOTATIONS, readonly: true, cacheable: true };
         }
         if (upper === 'DELETE') {
             return { ...DEFAULT_ANNOTATIONS, destructive: true };

package/dist/scanner.js.map

@@ -1 +1 @@
-{"version":3,"file":"scanner.js","sourceRoot":"","sources":["../src/scanner.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAEhD,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC,MAAM,OAAgB,WAAW;IAI/B,aAAa,CACX,OAAwB,EACxB,OAAgD;QAEhD,IAAI,MAAM,GAAG,OAAO,CAAC;QAErB,IAAI,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,CAAC;YAC7B,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;YAChC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;QACtE,CAAC;QAED,IAAI,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,CAAC;YAC7B,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;YAChC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;QACvE,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,MAAM,CAAC,0BAA0B,CAAC,MAAc;QAC9C,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC;QAEnC,IAAI,KAAK,KAAK,KAAK,EAAE,CAAC;YACpB,OAAO,EAAE,GAAG,mBAAmB,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;QACpD,CAAC;QACD,IAAI,KAAK,KAAK,QAAQ,EAAE,CAAC;YACvB,OAAO,EAAE,GAAG,mBAAmB,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;QACvD,CAAC;QACD,IAAI,KAAK,KAAK,KAAK,EAAE,CAAC;YACpB,OAAO,EAAE,GAAG,mBAAmB,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;QACtD,CAAC;QAED,OAAO,EAAE,GAAG,mBAAmB,EAAE,CAAC;IACpC,CAAC;IAED,cAAc,CAAC,OAAwB;QACrC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAkB,CAAC;QACvC,MAAM,MAAM,GAAoB,EAAE,CAAC;QAEnC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,MAAM,GAAG,GAAG,MAAM,CAAC,QAAQ,CAAC;YAC5B,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACjC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;YAEzB,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;gBACd,MAAM,KAAK,GAAG,GAAG,GAAG,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;gBACpC,MAAM,CAAC,IAAI,CACT,WAAW,CAAC,MAAM,EAAE;oBAClB,QAAQ,EAAE,KAAK;oBACf,QAAQ,EAAE;wBACR,GAAG,MAAM,CAAC,QAAQ;wBAClB,2BAA2B,GAAG,SAAS,KAAK,sBAAsB;qBACnE;iBACF,CAAC,CACH,CAAC;YACJ,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACtB,CAAC;QACH,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;CACF"}
+{"version":3,"file":"scanner.js","sourceRoot":"","sources":["../src/scanner.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apcore-toolkit",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Shared scanner, schema extraction, and output toolkit for apcore framework adapters",
   "type": "module",
   "main": "./dist/index.js",
@@ -50,17 +50,17 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "apcore-js": ">=0.9.0",
+    "apcore-js": "^0.13.0",
     "js-yaml": "^4.1.0"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^3.0.0",
     "apdev-js": "^0.2.0",
+    "eslint": "^9.0.0",
     "typescript": "^5.5.0",
-    "vitest": "^3.0.0",
-    "@vitest/coverage-v8": "^3.0.0",
-    "eslint": "^9.0.0"
+    "vitest": "^3.0.0"
   },
   "engines": {
     "node": ">=20.0.0"