@pleaseai/ask 0.1.0 → 0.2.0

package/dist/agents.d.ts

@@ -0,0 +1,2 @@
+export declare function generateAgentsMd(projectDir: string): string;
+//# sourceMappingURL=agents.d.ts.map

package/dist/agents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"AAOA,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAwF3D"}

package/dist/agents.js

@@ -0,0 +1,73 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { getLibraryDocsDir, listDocs } from './storage.js';
+const BEGIN_MARKER = '<!-- BEGIN:ask-docs-auto-generated -->';
+const END_MARKER = '<!-- END:ask-docs-auto-generated -->';
+export function generateAgentsMd(projectDir) {
+    const docs = listDocs(projectDir);
+    if (docs.length === 0)
+        return '';
+    const sections = docs.map(({ name, version }) => {
+        const docsRelPath = path.relative(projectDir, getLibraryDocsDir(projectDir, name, version));
+        const major = version.split('.')[0];
+        return `## ${name} v${version}
+
+> **WARNING:** This version may differ from your training data.
+> Read the docs in \`${docsRelPath}/\` before writing any ${name}-related code.
+> Heed deprecation notices and breaking changes.
+
+- **Version**: \`${version}\` — use \`"^${major}"\` in package.json (NOT older major versions)
+- Documentation: \`${docsRelPath}/\`
+- Index: \`${docsRelPath}/INDEX.md\``;
+    });
+    const generatedBlock = `${BEGIN_MARKER}
+# Documentation References
+
+The libraries in this project may have APIs and patterns that differ from your training data.
+**Always read the relevant documentation before writing code.**
+
+## .ask/docs/ — Vendored Documentation
+
+\`.ask/docs/\` contains third-party library documentation downloaded by ASK.
+Treat it as **read-only**: AI context should reference these files, but they are
+**not** subject to modification, lint, format, or code review. Updates are
+performed via \`ask docs sync\`.
+
+${sections.join('\n\n')}
+${END_MARKER}`;
+    // Read existing AGENTS.md and update or create
+    const agentsPath = path.join(projectDir, 'AGENTS.md');
+    if (fs.existsSync(agentsPath)) {
+        const existing = fs.readFileSync(agentsPath, 'utf-8');
+        const beginIdx = existing.indexOf(BEGIN_MARKER);
+        const endIdx = existing.indexOf(END_MARKER);
+        if (beginIdx !== -1 && endIdx !== -1) {
+            // Replace existing auto-generated block
+            const updated = existing.substring(0, beginIdx)
+                + generatedBlock
+                + existing.substring(endIdx + END_MARKER.length);
+            fs.writeFileSync(agentsPath, updated, 'utf-8');
+        }
+        else {
+            // Append to existing file
+            fs.writeFileSync(agentsPath, `${existing.trimEnd()}\n\n${generatedBlock}\n`, 'utf-8');
+        }
+    }
+    else {
+        fs.writeFileSync(agentsPath, `${generatedBlock}\n`, 'utf-8');
+    }
+    // Also create/update CLAUDE.md to reference AGENTS.md
+    const claudeMdPath = path.join(projectDir, 'CLAUDE.md');
+    const claudeRef = '@AGENTS.md';
+    if (fs.existsSync(claudeMdPath)) {
+        const claudeContent = fs.readFileSync(claudeMdPath, 'utf-8');
+        if (!claudeContent.includes(claudeRef)) {
+            fs.writeFileSync(claudeMdPath, `${claudeContent.trimEnd()}\n${claudeRef}\n`, 'utf-8');
+        }
+    }
+    else {
+        fs.writeFileSync(claudeMdPath, `${claudeRef}\n`, 'utf-8');
+    }
+    return agentsPath;
+}
+//# sourceMappingURL=agents.js.map

package/dist/agents.js.map

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

package/dist/concurrency.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Run an async function over a list of items with bounded concurrency.
+ *
+ * - Preserves input order in the result array (result[i] corresponds to items[i]).
+ * - Each `fn` invocation is independent. If `fn` rejects, that rejection
+ *   propagates — callers that need catch-and-continue semantics MUST wrap `fn`
+ *   to convert errors into a result variant.
+ * - `limit <= 0` is treated as unbounded (effectively `Promise.all`).
+ * - Empty input returns an empty array immediately without starting workers.
+ */
+export declare function runWithConcurrency<T, R>(items: readonly T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
+//# sourceMappingURL=concurrency.d.ts.map

package/dist/concurrency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"concurrency.d.ts","sourceRoot":"","sources":["../src/concurrency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAC3C,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GACzC,OAAO,CAAC,CAAC,EAAE,CAAC,CAqBd"}

package/dist/concurrency.js

@@ -0,0 +1,33 @@
+/**
+ * Run an async function over a list of items with bounded concurrency.
+ *
+ * - Preserves input order in the result array (result[i] corresponds to items[i]).
+ * - Each `fn` invocation is independent. If `fn` rejects, that rejection
+ *   propagates — callers that need catch-and-continue semantics MUST wrap `fn`
+ *   to convert errors into a result variant.
+ * - `limit <= 0` is treated as unbounded (effectively `Promise.all`).
+ * - Empty input returns an empty array immediately without starting workers.
+ */
+export async function runWithConcurrency(items, limit, fn) {
+    const results = Array.from({ length: items.length });
+    if (items.length === 0) {
+        return results;
+    }
+    const effectiveLimit = limit <= 0 ? items.length : Math.min(limit, items.length);
+    let next = 0;
+    async function worker() {
+        while (true) {
+            const i = next++;
+            if (i >= items.length)
+                return;
+            results[i] = await fn(items[i], i);
+        }
+    }
+    const workers = [];
+    for (let i = 0; i < effectiveLimit; i++) {
+        workers.push(worker());
+    }
+    await Promise.all(workers);
+    return results;
+}
+//# sourceMappingURL=concurrency.js.map

package/dist/concurrency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"concurrency.js","sourceRoot":"","sources":["../src/concurrency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,KAAmB,EACnB,KAAa,EACb,EAA0C;IAE1C,MAAM,OAAO,GAAQ,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAA;IACzD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,OAAO,CAAA;IAChB,CAAC;IACD,MAAM,cAAc,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;IAChF,IAAI,IAAI,GAAG,CAAC,CAAA;IACZ,KAAK,UAAU,MAAM;QACnB,OAAO,IAAI,EAAE,CAAC;YACZ,MAAM,CAAC,GAAG,IAAI,EAAE,CAAA;YAChB,IAAI,CAAC,IAAI,KAAK,CAAC,MAAM;gBACnB,OAAM;YACR,OAAO,CAAC,CAAC,CAAC,GAAG,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;QACpC,CAAC;IACH,CAAC;IACD,MAAM,OAAO,GAAoB,EAAE,CAAA;IACnC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,cAAc,EAAE,CAAC,EAAE,EAAE,CAAC;QACxC,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAA;IACxB,CAAC;IACD,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;IAC1B,OAAO,OAAO,CAAA;AAChB,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,8 @@
+import type { Config } from './schemas.js';
+import type { SourceConfig } from './sources/index.js';
+export type AskConfig = Config;
+export declare function loadConfig(projectDir: string): AskConfig;
+export declare function saveConfig(projectDir: string, config: AskConfig): void;
+export declare function addDocEntry(projectDir: string, entry: SourceConfig): AskConfig;
+export declare function removeDocEntry(projectDir: string, name: string, version?: string): AskConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAC1C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAGtD,MAAM,MAAM,SAAS,GAAG,MAAM,CAAA;AAE9B,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAExD;AAED,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI,CAEtE;AAED,wBAAgB,WAAW,CACzB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,YAAY,GAClB,SAAS,CAaX;AAED,wBAAgB,cAAc,CAC5B,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,MAAM,GACf,SAAS,CAOX"}

package/dist/config.js

@@ -0,0 +1,28 @@
+import { readConfig, writeConfig } from './io.js';
+export function loadConfig(projectDir) {
+    return readConfig(projectDir);
+}
+export function saveConfig(projectDir, config) {
+    writeConfig(projectDir, config);
+}
+export function addDocEntry(projectDir, entry) {
+    const config = loadConfig(projectDir);
+    // Replace existing entry for same name (regardless of version — versions
+    // change over time and we keep one entry per library)
+    const idx = config.docs.findIndex(d => d.name === entry.name);
+    if (idx >= 0) {
+        config.docs[idx] = entry;
+    }
+    else {
+        config.docs.push(entry);
+    }
+    saveConfig(projectDir, config);
+    return config;
+}
+export function removeDocEntry(projectDir, name, version) {
+    const config = loadConfig(projectDir);
+    config.docs = config.docs.filter(d => !(d.name === name && (!version || d.version === version)));
+    saveConfig(projectDir, config);
+    return config;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAIjD,MAAM,UAAU,UAAU,CAAC,UAAkB;IAC3C,OAAO,UAAU,CAAC,UAAU,CAAC,CAAA;AAC/B,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,UAAkB,EAAE,MAAiB;IAC9D,WAAW,CAAC,UAAU,EAAE,MAAM,CAAC,CAAA;AACjC,CAAC;AAED,MAAM,UAAU,WAAW,CACzB,UAAkB,EAClB,KAAmB;IAEnB,MAAM,MAAM,GAAG,UAAU,CAAC,UAAU,CAAC,CAAA;IACrC,yEAAyE;IACzE,sDAAsD;IACtD,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,KAAK,CAAC,IAAI,CAAC,CAAA;IAC7D,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC;QACb,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAA;IAC1B,CAAC;SACI,CAAC;QACJ,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IACzB,CAAC;IACD,UAAU,CAAC,UAAU,EAAE,MAAM,CAAC,CAAA;IAC9B,OAAO,MAAM,CAAA;AACf,CAAC;AAED,MAAM,UAAU,cAAc,CAC5B,UAAkB,EAClB,IAAY,EACZ,OAAgB;IAEhB,MAAM,MAAM,GAAG,UAAU,CAAC,UAAU,CAAC,CAAA;IACrC,MAAM,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAC9B,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,OAAO,KAAK,OAAO,CAAC,CAAC,CAC/D,CAAA;IACD,UAAU,CAAC,UAAU,EAAE,MAAM,CAAC,CAAA;IAC9B,OAAO,MAAM,CAAA;AACf,CAAC"}

package/dist/ignore-files.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Vendored docs ignore-file management.
+ *
+ * `.ask/docs/` contains third-party documentation downloaded by ASK. It
+ * should not be treated as project source: lint/format/code-review tools
+ * should skip it, but AI agents must still be able to read it as context.
+ *
+ * Strategy:
+ *   A. Write self-contained nested config files inside `.ask/docs/` for
+ *      tools that support hierarchical config resolution (Git, ESLint flat
+ *      config, Biome, markdownlint-cli2).
+ *   B. The "intent notice" for AI review tools lives in `agents.ts`
+ *      (extended `generateAgentsMd`).
+ *   C. Patch root files only for tools that do NOT support nested config
+ *      (Prettier, SonarQube, legacy markdownlint-cli).
+ */
+/**
+ * Category A: write nested config files inside `.ask/docs/`.
+ *
+ * The directory is created if it does not exist, so callers may invoke this
+ * before any docs have been saved. Existing files are only rewritten if
+ * their contents differ, to keep filesystem mtimes stable and logs terse.
+ *
+ * Returns the list of files that were created or updated (relative to the
+ * project root) so callers can log a summary.
+ */
+export declare function writeNestedConfigs(projectDir: string): string[];
+/**
+ * Remove all nested config files written by {@link writeNestedConfigs}.
+ *
+ * Only files with the exact names we manage are deleted. Other files
+ * inside `.ask/docs/` are left alone (including downloaded docs). Returns
+ * the list of removed file paths relative to the project root.
+ */
+export declare function removeNestedConfigs(projectDir: string): string[];
+/**
+ * Category C: patch root files that do not support nested ignore resolution.
+ *
+ * Only files that already exist are patched — ASK never creates a root
+ * ignore file from scratch, because doing so could imply a tool the user
+ * does not actually use.
+ */
+export declare function patchRootIgnores(projectDir: string): string[];
+/**
+ * Remove ASK-managed marker blocks from root files patched by
+ * {@link patchRootIgnores}. Files themselves are never deleted.
+ */
+export declare function unpatchRootIgnores(projectDir: string): string[];
+/**
+ * Top-level orchestrator called from the add/sync/remove commands.
+ *
+ * - `install` mode: create nested configs and patch detected root files.
+ * - `remove`  mode: delete nested configs and strip root marker blocks.
+ *
+ * Respects `manageIgnores` in `.ask/config.json` (default: true). When the
+ * flag is explicitly set to false, the function is a no-op.
+ */
+export declare function manageIgnoreFiles(projectDir: string, mode: 'install' | 'remove'): void;
+//# sourceMappingURL=ignore-files.d.ts.map

package/dist/ignore-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ignore-files.d.ts","sourceRoot":"","sources":["../src/ignore-files.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAsFH;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CAc/D;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CAahE;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CAmB7D;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CAc/D;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,SAAS,GAAG,QAAQ,GACzB,IAAI,CA2BN"}

package/dist/ignore-files.js

@@ -0,0 +1,205 @@
+/**
+ * Vendored docs ignore-file management.
+ *
+ * `.ask/docs/` contains third-party documentation downloaded by ASK. It
+ * should not be treated as project source: lint/format/code-review tools
+ * should skip it, but AI agents must still be able to read it as context.
+ *
+ * Strategy:
+ *   A. Write self-contained nested config files inside `.ask/docs/` for
+ *      tools that support hierarchical config resolution (Git, ESLint flat
+ *      config, Biome, markdownlint-cli2).
+ *   B. The "intent notice" for AI review tools lives in `agents.ts`
+ *      (extended `generateAgentsMd`).
+ *   C. Patch root files only for tools that do NOT support nested config
+ *      (Prettier, SonarQube, legacy markdownlint-cli).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { consola } from 'consola';
+import { loadConfig } from './config.js';
+import { inject, remove as removeMarker, wrap } from './markers.js';
+import { getDocsDir } from './storage.js';
+/**
+ * Local configuration files written inside `.ask/docs/` so that
+ * lint/format/review tools with nested-config support automatically skip
+ * the directory. Each file has a `name` (relative to `.ask/docs/`) and a
+ * `content` template.
+ */
+const NESTED_CONFIGS = [
+    {
+        name: '.gitattributes',
+        content: [
+            '# Managed by ASK — marks vendored docs for GitHub Linguist.',
+            '* linguist-vendored=true',
+            '* linguist-generated=true',
+            '',
+        ].join('\n'),
+    },
+    {
+        name: 'eslint.config.mjs',
+        content: [
+            '// Managed by ASK — vendored docs, excluded from ESLint.',
+            'export default [',
+            '  { ignores: [\'**/*\'] },',
+            ']',
+            '',
+        ].join('\n'),
+    },
+    {
+        name: 'biome.json',
+        content: `${JSON.stringify({
+            $schema: 'https://biomejs.dev/schemas/2.0.0/schema.json',
+            files: { ignore: ['**/*'] },
+        }, null, 2)}\n`,
+    },
+    {
+        name: '.markdownlint-cli2.jsonc',
+        content: `${JSON.stringify({ ignores: ['**/*'] }, null, 2)}\n`,
+    },
+];
+const ROOT_PATCHES = [
+    {
+        file: '.prettierignore',
+        syntax: 'hash',
+        payload: '# Vendored docs — managed by ASK\n.ask/docs/',
+    },
+    {
+        file: 'sonar-project.properties',
+        syntax: 'hash',
+        payload: '# Vendored docs — managed by ASK\nsonar.exclusions=.ask/docs/**',
+    },
+    {
+        file: '.markdownlintignore',
+        syntax: 'hash',
+        payload: '# Vendored docs — managed by ASK\n.ask/docs/',
+        warn: 'Legacy .markdownlintignore detected. Consider migrating to markdownlint-cli2, which supports nested config inside .ask/docs/ automatically.',
+    },
+];
+/**
+ * Category A: write nested config files inside `.ask/docs/`.
+ *
+ * The directory is created if it does not exist, so callers may invoke this
+ * before any docs have been saved. Existing files are only rewritten if
+ * their contents differ, to keep filesystem mtimes stable and logs terse.
+ *
+ * Returns the list of files that were created or updated (relative to the
+ * project root) so callers can log a summary.
+ */
+export function writeNestedConfigs(projectDir) {
+    const docsDir = getDocsDir(projectDir);
+    fs.mkdirSync(docsDir, { recursive: true });
+    const written = [];
+    for (const { name, content } of NESTED_CONFIGS) {
+        const target = path.join(docsDir, name);
+        const existing = fs.existsSync(target) ? fs.readFileSync(target, 'utf-8') : null;
+        if (existing !== content) {
+            fs.writeFileSync(target, content, 'utf-8');
+            written.push(path.relative(projectDir, target));
+        }
+    }
+    return written;
+}
+/**
+ * Remove all nested config files written by {@link writeNestedConfigs}.
+ *
+ * Only files with the exact names we manage are deleted. Other files
+ * inside `.ask/docs/` are left alone (including downloaded docs). Returns
+ * the list of removed file paths relative to the project root.
+ */
+export function removeNestedConfigs(projectDir) {
+    const docsDir = getDocsDir(projectDir);
+    if (!fs.existsSync(docsDir))
+        return [];
+    const removed = [];
+    for (const { name } of NESTED_CONFIGS) {
+        const target = path.join(docsDir, name);
+        if (fs.existsSync(target)) {
+            fs.rmSync(target);
+            removed.push(path.relative(projectDir, target));
+        }
+    }
+    return removed;
+}
+/**
+ * Category C: patch root files that do not support nested ignore resolution.
+ *
+ * Only files that already exist are patched — ASK never creates a root
+ * ignore file from scratch, because doing so could imply a tool the user
+ * does not actually use.
+ */
+export function patchRootIgnores(projectDir) {
+    const updated = [];
+    for (const patch of ROOT_PATCHES) {
+        const target = path.join(projectDir, patch.file);
+        if (!fs.existsSync(target))
+            continue;
+        const existing = fs.readFileSync(target, 'utf-8');
+        const block = wrap(patch.payload, patch.syntax);
+        const next = inject(existing, block, patch.syntax);
+        if (next !== existing) {
+            fs.writeFileSync(target, next, 'utf-8');
+            updated.push(patch.file);
+        }
+        if (patch.warn) {
+            consola.warn(patch.warn);
+        }
+    }
+    return updated;
+}
+/**
+ * Remove ASK-managed marker blocks from root files patched by
+ * {@link patchRootIgnores}. Files themselves are never deleted.
+ */
+export function unpatchRootIgnores(projectDir) {
+    const updated = [];
+    for (const patch of ROOT_PATCHES) {
+        const target = path.join(projectDir, patch.file);
+        if (!fs.existsSync(target))
+            continue;
+        const existing = fs.readFileSync(target, 'utf-8');
+        const next = removeMarker(existing, patch.syntax);
+        if (next !== existing) {
+            fs.writeFileSync(target, next, 'utf-8');
+            updated.push(patch.file);
+        }
+    }
+    return updated;
+}
+/**
+ * Top-level orchestrator called from the add/sync/remove commands.
+ *
+ * - `install` mode: create nested configs and patch detected root files.
+ * - `remove`  mode: delete nested configs and strip root marker blocks.
+ *
+ * Respects `manageIgnores` in `.ask/config.json` (default: true). When the
+ * flag is explicitly set to false, the function is a no-op.
+ */
+export function manageIgnoreFiles(projectDir, mode) {
+    // `loadConfig` returns a default empty config when `.ask/config.json`
+    // does not exist, and throws for corrupt/invalid files. We deliberately
+    // do NOT wrap this in a try/catch: callers should hear about a broken
+    // config rather than silently proceeding with mutations.
+    const config = loadConfig(projectDir);
+    if (config.manageIgnores === false) {
+        consola.info('Skipping ignore-file management (manageIgnores: false).');
+        return;
+    }
+    if (mode === 'install') {
+        const nested = writeNestedConfigs(projectDir);
+        const root = patchRootIgnores(projectDir);
+        if (nested.length > 0)
+            consola.info(`Nested configs written: ${nested.join(', ')}`);
+        if (root.length > 0)
+            consola.info(`Root ignore files patched: ${root.join(', ')}`);
+    }
+    else {
+        const nested = removeNestedConfigs(projectDir);
+        const root = unpatchRootIgnores(projectDir);
+        if (nested.length > 0)
+            consola.info(`Nested configs removed: ${nested.join(', ')}`);
+        if (root.length > 0)
+            consola.info(`Root ignore marker blocks removed: ${root.join(', ')}`);
+    }
+}
+//# sourceMappingURL=ignore-files.js.map

package/dist/ignore-files.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+import type { Lock } from './schemas.js';
+import type { SourceConfig } from './sources/index.js';
+/**
+ * Gate A: reject bare-name specs (`ask docs add next`).
+ *
+ * Bare names are ambiguous — they give the CLI no ecosystem hint and no
+ * explicit source, and silently auto-resolving them (which the old code did)
+ * can hand back wrong-looking docs. Instead we force the caller to either use
+ * an ecosystem prefix (`npm:next`) or the github shorthand (`owner/repo`).
+ *
+ * Returns an error message when the spec is ambiguous, or `null` when it is
+ * OK to proceed. `hasExplicitSource` lets the caller opt out of the check
+ * when `--source` is passed explicitly — an explicit source disambiguates.
+ */
+export declare function checkBareNameGate(input: string, parsedKind: 'github' | 'ecosystem' | 'name', hasExplicitSource: boolean): string | null;
+/**
+ * Gate B: manifest-based version resolution.
+ *
+ * When the user writes `npm:next` with no version, consult the project
+ * lockfile/manifest and try to use the installed version — this guarantees
+ * the downloaded docs match what's actually in the project.
+ *
+ * Resolution policy:
+ *   - lockfile exact hit → override version, log provenance
+ *   - manifest range hit → override version, log provenance (resolver will
+ *     later normalize the range)
+ *   - no hit + `--from-manifest` → error (user explicitly required manifest)
+ *   - no hit otherwise       → leave version as `'latest'` and fall through
+ *     to the existing resolver pipeline
+ *
+ * Returns `{ kind: 'ok', version? }` with the override version (or undefined
+ * if no override applied) or `{ kind: 'error', message }` when `--from-manifest`
+ * required a hit but we got none.
+ *
+ * The `readerFactory` argument is injectable so tests can supply mock readers
+ * without creating real lockfiles on disk.
+ */
+export type ManifestGateResult = {
+    kind: 'ok';
+    version?: string;
+    source?: string;
+} | {
+    kind: 'error';
+    message: string;
+};
+export declare function runManifestGate(ecosystem: string, name: string, version: string, projectDir: string, opts: {
+    noManifest: boolean;
+    fromManifest: boolean;
+}, readerFactory?: (eco: string) => {
+    readInstalledVersion: (n: string, d: string) => {
+        version: string;
+        source: string;
+        exact: boolean;
+    } | null;
+} | undefined): ManifestGateResult;
+type SyncStatus = 'drifted' | 'unchanged' | 'failed';
+export interface RunSyncOptions {
+    /**
+     * Override the per-entry sync function. Used by tests; defaults to the
+     * real `syncEntry` which performs network fetches and disk writes.
+     */
+    syncEntryFn?: (projectDir: string, entry: SourceConfig, lock: Lock) => Promise<SyncStatus>;
+    /**
+     * Skip the AGENTS.md regeneration step. Used by tests that don't care
+     * about that side effect.
+     */
+    skipAgentsMd?: boolean;
+}
+export declare function runSync(projectDir: string, options?: RunSyncOptions): Promise<{
+    drifted: number;
+    unchanged: number;
+    failed: number;
+}>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,KAAK,EAAE,IAAI,EAAa,MAAM,cAAc,CAAA;AACnD,OAAO,KAAK,EAKV,YAAY,EAEb,MAAM,oBAAoB,CAAA;AAsE3B;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,QAAQ,GAAG,WAAW,GAAG,MAAM,EAC3C,iBAAiB,EAAE,OAAO,GACzB,MAAM,GAAG,IAAI,CAWf;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,kBAAkB,GACxB;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAA;AAExC,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE;IAAE,UAAU,EAAE,OAAO,CAAC;IAAC,YAAY,EAAE,OAAO,CAAA;CAAE,EACpD,aAAa,GAAE,CAAC,GAAG,EAAE,MAAM,KAAK;IAAE,oBAAoB,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAA;CAAE,GAAG,SAAqB,GACrK,kBAAkB,CAsBpB;AAgQD,KAAK,UAAU,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAA;AAyEpD,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,UAAU,CAAC,CAAA;IAC1F;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;CACvB;AAED,wBAAsB,OAAO,CAC3B,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAoDjE"}