thachvd-kit 1.0.33 → 1.0.34

package/bin/entry.js

@@ -4,6 +4,8 @@ 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')) {
@@ -13,7 +15,63 @@ function isInitInvocation(args) {
     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');

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/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,6 +1,6 @@
 {
     "name": "thachvd-kit",
-    "version": "1.0.33",
+    "version": "1.0.34",
     "description": "Cross-agent project rules bootstrap kit for Codex, Antigravity, and Claude Code",
     "bin": {
         "thachvd-kit": "./bin/entry.js"
@@ -15,8 +15,8 @@
         "node": ">=16.7"
     },
     "scripts": {
-        "test": "node test/cli.test.js && node test/policy.test.js",
-        "release:verify": "npm test && node --check bin/cli.js && node --check bin/entry.js && node --check bin/policy.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",