thachvd-kit 1.0.32 → 1.0.34

package/bin/entry.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+
+const {
+    snapshotPolicyFiles,
+    applyPolicyUpgrades
+} = require('./policy');
+const { upgradeProject } = require('./upgrade');
+const { installGlobalPolicies } = require('./global');
+
+function isInitInvocation(args) {
+    if (args.includes('--help') || args.includes('-h') || args.includes('--version') || args.includes('-v')) {
+        return false;
+    }
+    const first = args[0];
+    return !first || first === 'init' || first.startsWith('-');
+}
+
+function runUpgrade(args) {
+    const results = upgradeProject(process.cwd(), { dryRun: args.includes('--dry-run') });
+    const changed = results.filter(result => result.changed);
+    if (changed.length === 0) {
+        console.log('No managed project policy changes needed.');
+        return;
+    }
+    for (const result of changed) {
+        console.log(`${result.dryRun ? 'WOULD UPDATE' : 'UPDATED'} ${result.path}`);
+    }
+}
+
+function runGlobal(args) {
+    const homeDir = process.env.USERPROFILE || process.env.HOME;
+    if (!homeDir) {
+        console.error('Cannot determine home directory from USERPROFILE or HOME.');
+        process.exitCode = 1;
+        return;
+    }
+
+    const antigravityOnly = args.includes('--antigravity-only');
+    const codexOnly = args.includes('--codex-only');
+    if (antigravityOnly && codexOnly) {
+        console.error('Choose at most one of --antigravity-only or --codex-only.');
+        process.exitCode = 1;
+        return;
+    }
+
+    const results = installGlobalPolicies(homeDir, {
+        antigravityOnly,
+        codexOnly,
+        dryRun: args.includes('--dry-run')
+    });
+
+    for (const result of results) {
+        const status = result.changed ? (result.dryRun ? 'WOULD UPDATE' : 'UPDATED') : 'OK';
+        console.log(`${status} ${result.path}`);
+    }
+
+    if (results.some(result => result.changed) && !args.includes('--dry-run')) {
+        console.log('Restart Antigravity/Codex sessions so the updated global instructions are reloaded.');
+    }
+}
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+if (command === 'upgrade') {
+    runUpgrade(args.slice(1));
+    return;
+}
+
+if (command === 'global') {
+    runGlobal(args.slice(1));
+    return;
+}
+
+const shouldUpgradeGeneratedPolicy = isInitInvocation(args);
+const beforeSnapshot = shouldUpgradeGeneratedPolicy ? snapshotPolicyFiles(process.cwd()) : null;
+const force = args.includes('--yes') || args.includes('-y');
+
+if (shouldUpgradeGeneratedPolicy) {
+    process.once('beforeExit', code => {
+        if (code !== 0 || (process.exitCode && process.exitCode !== 0)) return;
+        const changed = applyPolicyUpgrades(process.cwd(), beforeSnapshot, { force });
+        if (changed.length > 0) {
+            console.log(`  OK Applied engineering quality policy to ${changed.length} generated context file(s)`);
+        }
+    });
+}
+
+require('./cli');

package/bin/global.js

@@ -0,0 +1,103 @@
+const fs = require('fs');
+const path = require('path');
+
+const START = '<!-- thachvd-kit:global-tool-routing:start -->';
+const END = '<!-- thachvd-kit:global-tool-routing:end -->';
+
+const GLOBAL_TOOL_ROUTING = `${START}
+## AI Coding Tool Routing
+
+Optimize tool usage for correctness and context efficiency.
+
+### Core principle
+
+Use the cheapest reliable source that can answer the question. Do not perform broad repository searches when structural tools can answer the question more precisely, and do not retrieve the same evidence twice once sufficient context is available.
+
+This routing policy supersedes older blanket instructions such as “ALWAYS prefer MCP graph tools over grep/glob/file-search”. Graph-first is preferred for structural discovery, not for every search.
+
+### Code discovery
+
+- For unknown code ownership, symbols, callers/callees, architecture, dependencies, or impact analysis, prefer one available structural index such as \`codebase-memory-mcp\` or CodeGraph.
+- If multiple structural indexes are available, choose one first. Do not query both for the same question unless the first result is insufficient or stale.
+- Once the relevant file or symbol is known, read only the specific code needed for the task.
+
+### Direct search
+
+Use \`rg\`, \`grep\`, globbing, or direct file reads when they are the more precise and cheaper operation, including exact strings, error messages, config values, environment variables, TODO/FIXME markers, filenames, non-code files, and known narrow locations.
+
+Avoid broad repository-wide text searches for structural questions.
+
+### Shell output
+
+Prefer RTK for verbose commands when it supports the command and preserves the information needed, especially git status/diff/log, tests, builds, package-manager commands, Docker, Kubernetes, and noisy linters.
+
+Use raw command output when RTK is unavailable, incompatible, or raw output is specifically required for diagnosis.
+
+### Context budget
+
+Treat tool output as part of the model context budget. Narrow searches and commands before running them, avoid duplicate retrieval, and request only the relevant file, symbol, range, test, or log section.
+
+Correctness takes priority over token savings. Never omit context required to make a safe and correct change.
+${END}`;
+
+function normalize(text) {
+    return String(text || '').replace(/\r\n/g, '\n');
+}
+
+function upsertManagedBlock(content, block = GLOBAL_TOOL_ROUTING) {
+    const text = normalize(content);
+    const start = text.indexOf(START);
+    const end = text.indexOf(END);
+
+    if (start >= 0 && end >= start) {
+        const after = end + END.length;
+        return `${text.slice(0, start)}${block}${text.slice(after)}`.replace(/\n{3,}/g, '\n\n').trimEnd() + '\n';
+    }
+
+    const prefix = text.trimEnd();
+    return `${prefix}${prefix ? '\n\n' : ''}${block}\n`;
+}
+
+function resolveCodexGlobalTarget(homeDir) {
+    const codexDir = path.join(homeDir, '.codex');
+    const overridePath = path.join(codexDir, 'AGENTS.override.md');
+    if (fs.existsSync(overridePath) && fs.statSync(overridePath).size > 0) return overridePath;
+    return path.join(codexDir, 'AGENTS.md');
+}
+
+function installGlobalRouting(filePath, options = {}) {
+    const dryRun = options.dryRun === true;
+    const existing = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '';
+    const updated = upsertManagedBlock(existing);
+    const changed = normalize(existing) !== updated;
+
+    if (changed && !dryRun) {
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.writeFileSync(filePath, updated, 'utf8');
+    }
+
+    return { path: filePath, changed, dryRun: changed && dryRun };
+}
+
+function installGlobalPolicies(homeDir, options = {}) {
+    const antigravityOnly = options.antigravityOnly === true;
+    const codexOnly = options.codexOnly === true;
+    if (antigravityOnly && codexOnly) {
+        throw new Error('Choose at most one of antigravityOnly or codexOnly.');
+    }
+
+    const targets = [];
+    if (!codexOnly) targets.push(path.join(homeDir, '.gemini', 'GEMINI.md'));
+    if (!antigravityOnly) targets.push(resolveCodexGlobalTarget(homeDir));
+    return targets.map(filePath => installGlobalRouting(filePath, options));
+}
+
+module.exports = {
+    START,
+    END,
+    GLOBAL_TOOL_ROUTING,
+    upsertManagedBlock,
+    resolveCodexGlobalTarget,
+    installGlobalRouting,
+    installGlobalPolicies
+};

package/bin/policy.js

@@ -0,0 +1,196 @@
+const fs = require('fs');
+const path = require('path');
+
+const POLICY_PATHS = [
+    'AGENTS.md',
+    '.cursorrules',
+    path.join('.agent', 'docs', 'conventions.md'),
+    path.join('.agent', 'docs', 'workflow.md'),
+    path.join('.agent', 'docs', 'getting-started.md'),
+    path.join('.agent', 'docs', 'tooling.md')
+];
+
+const QUALITY_FLOOR_SECTION = `## Engineering Quality Floor
+
+Prefer the smallest sufficient change, not the fewest lines of code.
+
+A simpler implementation is acceptable only when it fully preserves:
+
+- required behavior and acceptance criteria;
+- existing product and architectural contracts;
+- UX and accessibility behavior;
+- security and data integrity;
+- compatibility and expected performance;
+- maintainability appropriate to the codebase.
+
+Do not bypass an existing project abstraction merely because a lower-level primitive requires less code. Existing abstractions may encode product behavior and implicit requirements. Do not introduce speculative abstractions either; add complexity only when concrete requirements or codebase evidence justify it.`;
+
+const AGENT_RULES_SECTION = `## Rules
+
+- Respond in the user's language; keep code, identifiers, and code comments in English.
+- State assumptions when the request is ambiguous.
+- Prefer established project patterns and abstractions when they satisfy the required contract.
+- Keep changes surgical, but never trade away required behavior, UX, accessibility, security, data integrity, compatibility, or maintainability just to reduce code.
+- Do not split or reorganize code solely to satisfy a line-count target. Prefer cohesive modules with clear responsibilities; split only for a concrete cohesion, ownership, testability, or maintainability benefit.
+- **Context retrieval**: use the cheapest source that can answer the question reliably. Read/search directly for a known local file or obvious local edit; use \`codebase-memory-mcp\` or another configured structural index for unknown ownership, symbol relationships, call paths, architecture, or impact; use \`context7\` for external API/docs uncertainty; use \`playwright\` for browser/UI verification. Avoid duplicate retrieval when one source already provides sufficient evidence.
+- Prefer \`rtk\` by default for verbose shell commands such as git, tests, builds, package managers, Docker, and Kubernetes. Run the underlying command directly when RTK is unavailable or incompatible.
+- Tests or equivalent verification are mandatory before claiming completion.`;
+
+const CONVENTIONS_STANDARDS_SECTION = `## Current Standards
+
+- Code comments and identifiers should be written in English.
+- Keep changes scoped to the user request and preserve established local conventions.
+- Prefer existing project abstractions when they satisfy the required contract; do not bypass them solely to save lines of code.
+- Do not split or reorganize code solely to satisfy a line-count target. Prefer cohesive modules with clear responsibilities.
+- Add abstractions only when concrete requirements or codebase evidence justify them.
+- TODO: refine naming, formatting, folder, API, state, styling, and testing conventions from the real codebase.`;
+
+const FAST_PATH_SECTION = `## Fast Path
+
+Fast-path eligibility is based on risk and contract surface, not file count. Use it only when the change is localized, mechanically obvious, has no meaningful public API, schema, security, data-integrity, dependency, CI/release, or architectural risk, and has focused verification available. A two-file change such as code plus its focused test may still be fast-path; a one-file auth, payment, schema, concurrency, or other high-risk change is not.
+
+State the narrow scope and verification before editing. If the task becomes ambiguous, introduces new behavior or architectural decisions, or its risk/contract surface grows, switch to brainstorming and planning.`;
+
+const GETTING_STARTED_FAST_PATH_SECTION = `## Fast Path
+
+Use a fast path when the change is localized, mechanically obvious, low-risk, and has focused verification. File count alone does not determine eligibility: code plus a focused test can still be trivial, while a one-file security, schema, payment, concurrency, or public-contract change requires the full workflow. If scope or risk grows, return to brainstorming and planning.`;
+
+const TOOL_ROUTING_SECTION = `## Tool Routing
+
+Use the cheapest source that can answer the question reliably and avoid retrieving the same evidence twice.
+
+- Known local file or obvious local edit: read/search directly.
+- Unknown ownership, symbol relationships, call paths, architecture, or impact: use \`codebase-memory-mcp\` or another configured structural index such as CodeGraph.
+- External library/API uncertainty: use Context7.
+- Browser/UI behavior: use Playwright.
+- Noisy shell output: prefer RTK.
+
+Structural tools are aids, not mandatory ceremony. If direct evidence is already sufficient, do not call extra MCP tools just because they are available.`;
+
+function normalizeNewlines(text) {
+    return String(text || '').replace(/\r\n/g, '\n');
+}
+
+function replaceSection(markdown, heading, replacement) {
+    const text = normalizeNewlines(markdown);
+    const marker = `${heading}\n`;
+    const start = text.indexOf(marker);
+    if (start < 0) return text;
+
+    const searchFrom = start + marker.length;
+    const nextHeading = text.indexOf('\n## ', searchFrom);
+    const end = nextHeading >= 0 ? nextHeading + 1 : text.length;
+    const prefix = text.slice(0, start);
+    const suffix = text.slice(end).replace(/^\n+/, '');
+    return `${prefix}${replacement.trimEnd()}\n\n${suffix}`.replace(/\n{3,}/g, '\n\n');
+}
+
+function insertSectionBefore(markdown, beforeHeading, section) {
+    const text = normalizeNewlines(markdown);
+    const sectionHeading = section.split('\n', 1)[0];
+    if (text.includes(`${sectionHeading}\n`)) return text;
+
+    const marker = `${beforeHeading}\n`;
+    const index = text.indexOf(marker);
+    if (index < 0) return `${text.trimEnd()}\n\n${section.trimEnd()}\n`;
+    return `${text.slice(0, index)}${section.trimEnd()}\n\n${text.slice(index)}`;
+}
+
+function replaceFastPathInline(markdown) {
+    return normalizeNewlines(markdown)
+        .replace(
+            'Questions and research do not edit product code. A simple fix may use a fast path only when it is one-file, unambiguous, and changes no behavior or contract. State the scope and verification before editing. If the scope grows, switch to the full Superpowers flow.',
+            'Questions and research do not edit product code. A fast path is allowed only when the change is localized, mechanically obvious, low-risk, and has focused verification; file count alone is not a gate. State the scope and verification before editing. If the task becomes ambiguous or its behavior, contract, or risk surface grows, switch to the full Superpowers flow.'
+        )
+        .replace(
+            'Questions and research do not edit product code. A simple fix may use a fast path only when it is one-file, unambiguous, and changes no behavior or contract. State the narrow scope and verification before editing. If the scope grows, return to brainstorming and planning.',
+            'Questions and research do not edit product code. A fast path is allowed only when the change is localized, mechanically obvious, low-risk, and has focused verification; file count alone is not a gate. State the narrow scope and verification before editing. If scope or risk grows, return to brainstorming and planning.'
+        );
+}
+
+function upgradeAgentsMarkdown(markdown) {
+    let text = replaceFastPathInline(markdown);
+    text = insertSectionBefore(text, '## Rules', QUALITY_FLOOR_SECTION);
+    text = replaceSection(text, '## Rules', AGENT_RULES_SECTION);
+    return text.trimEnd() + '\n';
+}
+
+function upgradeConventionsMarkdown(markdown) {
+    let text = replaceSection(markdown, '## Current Standards', CONVENTIONS_STANDARDS_SECTION);
+    text = insertSectionBefore(text, '## Verification', QUALITY_FLOOR_SECTION);
+    return text.trimEnd() + '\n';
+}
+
+function upgradeWorkflowMarkdown(markdown) {
+    return replaceSection(markdown, '## Fast Path', FAST_PATH_SECTION).trimEnd() + '\n';
+}
+
+function upgradeGettingStartedMarkdown(markdown) {
+    return replaceSection(markdown, '## Fast Path', GETTING_STARTED_FAST_PATH_SECTION).trimEnd() + '\n';
+}
+
+function upgradeToolingMarkdown(markdown) {
+    const text = normalizeNewlines(markdown);
+    const targetHeading = text.includes('## Codebase Memory MCP\n')
+        ? '## Codebase Memory MCP'
+        : '## codebase-memory-mcp';
+    return insertSectionBefore(text, targetHeading, TOOL_ROUTING_SECTION).trimEnd() + '\n';
+}
+
+function upgradeGeneratedContent(relativePath, content) {
+    const normalized = relativePath.split(path.sep).join('/');
+    if (normalized === 'AGENTS.md' || normalized === '.cursorrules') return upgradeAgentsMarkdown(content);
+    if (normalized.endsWith('/conventions.md')) return upgradeConventionsMarkdown(content);
+    if (normalized.endsWith('/workflow.md')) return upgradeWorkflowMarkdown(content);
+    if (normalized.endsWith('/getting-started.md')) return upgradeGettingStartedMarkdown(content);
+    if (normalized.endsWith('/tooling.md')) return upgradeToolingMarkdown(content);
+    return normalizeNewlines(content);
+}
+
+function snapshotPolicyFiles(rootDir) {
+    const snapshot = new Map();
+    for (const relativePath of POLICY_PATHS) {
+        const fullPath = path.join(rootDir, relativePath);
+        snapshot.set(relativePath, fs.existsSync(fullPath) ? fs.readFileSync(fullPath, 'utf8') : null);
+    }
+    return snapshot;
+}
+
+function applyPolicyUpgrades(rootDir, beforeSnapshot, options = {}) {
+    const force = options.force === true;
+    const changed = [];
+
+    for (const relativePath of POLICY_PATHS) {
+        const fullPath = path.join(rootDir, relativePath);
+        if (!fs.existsSync(fullPath)) continue;
+
+        const current = fs.readFileSync(fullPath, 'utf8');
+        const before = beforeSnapshot ? beforeSnapshot.get(relativePath) : null;
+        const wasWritten = force || before === null || before !== current;
+        if (!wasWritten) continue;
+
+        const upgraded = upgradeGeneratedContent(relativePath, current);
+        if (upgraded !== normalizeNewlines(current)) {
+            fs.writeFileSync(fullPath, upgraded, 'utf8');
+            changed.push(relativePath);
+        }
+    }
+
+    return changed;
+}
+
+module.exports = {
+    POLICY_PATHS,
+    QUALITY_FLOOR_SECTION,
+    AGENT_RULES_SECTION,
+    FAST_PATH_SECTION,
+    TOOL_ROUTING_SECTION,
+    upgradeGeneratedContent,
+    upgradeAgentsMarkdown,
+    upgradeConventionsMarkdown,
+    upgradeWorkflowMarkdown,
+    upgradeGettingStartedMarkdown,
+    upgradeToolingMarkdown,
+    snapshotPolicyFiles,
+    applyPolicyUpgrades
+};

package/bin/upgrade.js

@@ -0,0 +1,86 @@
+const fs = require('fs');
+const path = require('path');
+
+const START = '<!-- thachvd-kit:project-policy:start -->';
+const END = '<!-- thachvd-kit:project-policy:end -->';
+
+const PROJECT_POLICY = `${START}
+## Engineering Policy
+
+Prefer the smallest sufficient change, not the fewest lines of code.
+
+- Preserve required behavior, product and architectural contracts, UX/accessibility, security/data integrity, compatibility/performance, and maintainability before optimizing for simplicity.
+- Reuse an existing project abstraction when it satisfies the required contract. Do not bypass it merely because a lower-level primitive is shorter.
+- Avoid speculative abstractions and unrelated refactors.
+- Do not split or reorganize code solely to satisfy a line-count target. Prefer cohesive modules and split only for a concrete cohesion, ownership, testability, or maintainability benefit.
+- Fast-path eligibility is based on risk and contract surface, not file count. A code change plus its focused test can still be trivial; a one-file auth, payment, schema, concurrency, or public-contract change is not.
+- Use the cheapest reliable context source. Read/search directly for known local code and exact text; use one structural index such as codebase-memory-mcp or CodeGraph for unknown ownership, call paths, architecture, or impact; avoid duplicate retrieval once sufficient evidence is available.
+- Prefer RTK for verbose shell output when it preserves the information needed. Use raw output when required for diagnosis.
+- Tests or equivalent verification are mandatory before claiming completion.
+${END}`;
+
+const TARGETS = [
+    'AGENTS.md',
+    path.join('.agent', 'docs', 'conventions.md'),
+    path.join('.agent', 'docs', 'workflow.md'),
+    path.join('.agent', 'docs', 'tooling.md')
+];
+
+function normalize(text) {
+    return String(text || '').replace(/\r\n/g, '\n');
+}
+
+function removeKnownObsoleteDefaults(text) {
+    return normalize(text)
+        .replace(/^\s*- Maximum file length: 300 lines unless the existing project standard is stricter\.\s*\n?/gm, '')
+        .replace(/^\s*- Keep files under 300 lines unless the project already has a different standard[^\n]*\n?/gm, '')
+        .replace(/^\s*- \*\*MCP First\*\*:[^\n]*\n?/gm, '')
+        .replace(/^\s*- Use MCP first for code discovery and technical documentation;[^\n]*\n?/gm, '')
+        .replace(/Use it only for one-file, unambiguous changes with no behavior, API, schema, security, dependency, CI, workflow, or release contract change\.[^\n]*/g,
+            'Fast-path eligibility is based on risk and contract surface, not file count. Use it only for localized, mechanically obvious, low-risk changes with focused verification.')
+        .replace(/Use a fast path only for one-file, unambiguous changes with no behavior or contract change\.[^\n]*/g,
+            'Use a fast path only for localized, mechanically obvious, low-risk changes with focused verification; file count alone is not a gate.')
+        .replace(/\n{3,}/g, '\n\n');
+}
+
+function upsertManagedBlock(content) {
+    let text = removeKnownObsoleteDefaults(content);
+    const start = text.indexOf(START);
+    const end = text.indexOf(END);
+
+    if (start >= 0 && end >= start) {
+        const after = end + END.length;
+        return `${text.slice(0, start)}${PROJECT_POLICY}${text.slice(after)}`.replace(/\n{3,}/g, '\n\n').trimEnd() + '\n';
+    }
+
+    const trimmed = text.trimEnd();
+    return `${trimmed}${trimmed ? '\n\n' : ''}${PROJECT_POLICY}\n`;
+}
+
+function upgradeProject(rootDir, options = {}) {
+    const dryRun = options.dryRun === true;
+    const results = [];
+
+    for (const relativePath of TARGETS) {
+        const fullPath = path.join(rootDir, relativePath);
+        if (!fs.existsSync(fullPath)) continue;
+
+        const existing = fs.readFileSync(fullPath, 'utf8');
+        const updated = upsertManagedBlock(existing);
+        const changed = normalize(existing) !== updated;
+        if (changed && !dryRun) fs.writeFileSync(fullPath, updated, 'utf8');
+        results.push({ path: relativePath, changed, dryRun: changed && dryRun });
+    }
+
+    return results;
+}
+
+module.exports = {
+    START,
+    END,
+    PROJECT_POLICY,
+    TARGETS,
+    removeKnownObsoleteDefaults,
+    upsertManagedBlock,
+    upgradeProject
+};

package/package.json

@@ -1,9 +1,9 @@
 {
     "name": "thachvd-kit",
-    "version": "1.0.32",
+    "version": "1.0.34",
     "description": "Cross-agent project rules bootstrap kit for Codex, Antigravity, and Claude Code",
     "bin": {
-        "thachvd-kit": "./bin/cli.js"
+        "thachvd-kit": "./bin/entry.js"
     },
     "files": [
         "bin",
@@ -15,8 +15,8 @@
         "node": ">=16.7"
     },
     "scripts": {
-        "test": "node test/cli.test.js",
-        "release:verify": "npm test && node --check bin/cli.js && npm pack --dry-run",
+        "test": "node test/cli.test.js && node test/policy.test.js && node test/upgrade.test.js && node test/global.test.js",
+        "release:verify": "npm test && node --check bin/cli.js && node --check bin/entry.js && node --check bin/policy.js && node --check bin/upgrade.js && node --check bin/global.js && npm pack --dry-run",
         "preversion": "npm run release:verify",
         "release:patch": "npm version patch",
         "release:dry-run": "npm pack --dry-run",