@freshworks/shiftleft-tools 1.1.8

package/src/commands/update.js

@@ -0,0 +1,203 @@
+import { existsSync } from 'fs';
+import { join } from 'path';
+import ora from 'ora';
+import inquirer from 'inquirer';
+import { syncTemplate } from '../utils/template.js';
+import {
+    loadManifest,
+    createManifest,
+    saveManifest,
+    getToolVersion,
+} from '../utils/manifest.js';
+import { detectStack, inferServiceName, buildContext } from '../utils/stack.js';
+import { ensureGitignoreEntries } from '../utils/gitignore.js';
+import { linkAssets } from './link.js';
+import { stageScripts, STAGED_GITIGNORE_ENTRIES, STAGED_GITIGNORE_HEADER } from './run-tests.js';
+import { logger } from '../utils/logger.js';
+
+/**
+ * Update rules/skills/postman to latest version.
+ *
+ * Manifest-aware: branches on the three-way file state per file instead of
+ * blindly overwriting. Locally-edited files are never silently clobbered —
+ * a `<file>.shiftleft-new` is written beside them instead (unless --force).
+ */
+export async function update(options) {
+    const cwd = process.cwd();
+
+    // Determine what to update
+    const updateAll = !options.rules && !options.skills && !options.postman;
+    const updateRules = options.rules || updateAll;
+    const updateSkills = options.skills || updateAll;
+    const updatePostman = options.postman || updateAll;
+
+    // Confirm if not forcing
+    if (!options.force) {
+        const targets = [];
+        if (updateRules) targets.push('rules');
+        if (updateSkills) targets.push('skills');
+        if (updatePostman) targets.push('postman scripts');
+
+        const { confirm } = await inquirer.prompt([
+            {
+                type: 'confirm',
+                name: 'confirm',
+                message: `Update ${targets.join(', ')} to the latest version? (locally-edited files are preserved; use --force to overwrite them.)`,
+                default: true,
+            },
+        ]);
+
+        if (!confirm) {
+            logger.info('Update cancelled.');
+            return;
+        }
+    }
+
+    // Load (or adopt) the manifest. On a repo that has none, the first run
+    // seeds a baseline from current disk content so out-of-date files update
+    // cleanly rather than being flagged as conflicts.
+    let manifest = loadManifest(cwd);
+    const adopt = manifest === null;
+    if (adopt) {
+        manifest = createManifest(detectStack(cwd) || null);
+        logger.info('No .shiftleft.json found — adopting current files as the baseline.');
+    }
+    manifest.toolVersion = getToolVersion();
+
+    const totals = { copied: 0, skipped: 0, conflicts: 0 };
+
+    if (updateRules) {
+        accumulate(totals, await updateRulesFiles(cwd, manifest, options.force, adopt));
+    }
+
+    if (updateSkills) {
+        accumulate(totals, await updateSkillsFiles(cwd, manifest));
+    }
+
+    if (updatePostman) {
+        accumulate(totals, await updatePostmanScripts(cwd, manifest, options.force, adopt));
+    }
+
+    saveManifest(cwd, manifest);
+
+    console.log();
+    logger.success(
+        `Update complete: ${totals.copied} updated, ${totals.skipped} unchanged, ${totals.conflicts} conflict(s).`
+    );
+    if (totals.conflicts > 0) {
+        logger.warn(
+            'Some files had local edits and were left untouched. Review the *.shiftleft-new files, '
+            + 'then merge by hand or re-run with --force to overwrite.'
+        );
+    }
+}
+
+function accumulate(totals, result) {
+    if (!result) return;
+    totals.copied += result.copied || 0;
+    totals.skipped += result.skipped || 0;
+    totals.conflicts += result.conflicts || 0;
+}
+
+function tally(result, status) {
+    if (status === 'conflict') result.conflicts++;
+    else if (status === 'uptodate' || status === 'skipped') result.skipped++;
+    else result.copied++;
+}
+
+async function updateRulesFiles(cwd, manifest, force, adopt) {
+    const spinner = ora('Updating rules...').start();
+    const result = { copied: 0, skipped: 0, conflicts: 0 };
+
+    // Cursor rules now resolve via symlinks to the installed package; refresh
+    // them rather than copying. Falls back to copies where symlinks are denied.
+    const { linked, copied } = linkAssets(cwd, {
+        stack: manifest.stack || detectStack(cwd),
+        skills: false,
+        rules: true,
+        manifest,
+    });
+    // Symlink refreshes are idempotent — count as unchanged, not updated.
+    result.skipped += linked.length;
+    result.copied += copied.length;
+
+    // CLAUDE.md and AGENTS.md remain real, manifest-managed files.
+    const claudeMdDest = join(cwd, 'CLAUDE.md');
+    if (existsSync(claudeMdDest)) {
+        tally(result, syncTemplate('CLAUDE.md', claudeMdDest, {}, { manifest, cwd, force, adopt }).status);
+    }
+    tally(result, syncTemplate('AGENTS.md', join(cwd, 'AGENTS.md'), {}, { manifest, cwd, force, adopt }).status);
+
+    spinner.succeed(`Rules: ${linked.length} linked, ${copied.length} copied, CLAUDE/AGENTS ${result.conflicts ? `${result.conflicts} conflict(s)` : 'in sync'}`);
+    return result;
+}
+
+async function updateSkillsFiles(cwd, manifest) {
+    const spinner = ora('Updating skills...').start();
+    const result = { copied: 0, skipped: 0, conflicts: 0 };
+
+    // Cursor skills resolve via a symlink to the package; Claude Code skills
+    // come from the plugin. Refresh the Cursor symlink.
+    const { linked, copied } = linkAssets(cwd, {
+        stack: manifest.stack || detectStack(cwd),
+        skills: true,
+        rules: false,
+        manifest,
+    });
+    // Symlink refreshes are idempotent — count as unchanged, not updated.
+    result.skipped += linked.length;
+    result.copied += copied.length;
+
+    spinner.succeed(
+        linked.length
+            ? 'Skills: Cursor symlink refreshed (Claude skills via plugin)'
+            : `Skills: ${copied.length} copied (symlinks unavailable; Claude skills via plugin)`
+    );
+    return result;
+}
+
+async function updatePostmanScripts(cwd, manifest, force, adopt) {
+    const spinner = ora('Updating postman scripts...').start();
+    const scriptsDir = join(cwd, 'postman/scripts');
+    const result = { copied: 0, skipped: 0, conflicts: 0 };
+
+    if (!existsSync(scriptsDir)) {
+        spinner.warn('No postman/scripts directory found. Run "shiftleft init-postman" first.');
+        return result;
+    }
+
+    const stack = manifest.stack || detectStack(cwd);
+    const context = buildContext(inferServiceName(cwd), stack);
+
+    // The committed entrypoint becomes a thin shim; orchestration lives in the
+    // package. A locally-edited run-all.sh still gets conflict treatment.
+    tally(result, syncTemplate('postman/run-all-shim.sh', join(scriptsDir, 'run-all.sh'), context, {
+        manifest, cwd, force, adopt,
+    }).status);
+
+    // Library scripts are no longer vendored: drop their manifest entries.
+    // (The committed copies, if any, stay in git until the team removes them;
+    // staging refreshes the on-disk versions before every run.)
+    let pruned = 0;
+    for (const key of Object.keys(manifest.managed)) {
+        if (
+            key.startsWith('postman/scripts/') &&
+            key !== 'postman/scripts/run-all.sh' &&
+            key !== 'postman/scripts/setup-mocks.js'
+        ) {
+            delete manifest.managed[key];
+            pruned++;
+        }
+    }
+
+    ensureGitignoreEntries(join(cwd, 'postman/.gitignore'), STAGED_GITIGNORE_ENTRIES, STAGED_GITIGNORE_HEADER);
+
+    const { staged } = stageScripts(cwd, { stack });
+
+    spinner.succeed(
+        `Postman scripts: shim in sync, ${staged} library scripts staged from package`
+        + (pruned ? `, ${pruned} legacy manifest entries pruned` : '')
+        + (result.conflicts ? `, ${result.conflicts} conflict(s)` : '')
+    );
+    return result;
+}

package/src/index.js

@@ -0,0 +1,4 @@
+export { initRules } from './commands/init-rules.js';
+export { initPostman } from './commands/init-postman.js';
+export { update } from './commands/update.js';
+export { setupPipeline } from './commands/setup-pipeline.js';

package/src/utils/copy-tree.js

@@ -0,0 +1,98 @@
+import { existsSync, readdirSync, statSync } from 'fs';
+import { join, relative } from 'path';
+import { copyTemplate, syncTemplate, ensureDir, TEMPLATES_DIR } from './template.js';
+import { recordFile } from './manifest.js';
+
+/**
+ * Recursively copy a template directory into a destination directory.
+ * Files ending in .ejs are rendered and written without the .ejs suffix.
+ *
+ * Modes:
+ *  - default (no `manifest`): "create" semantics — skip existing unless `force`.
+ *  - `sync: true` + `manifest`: manifest-aware three-way write per file.
+ *  - `manifest` without `sync`: create semantics, but record each written file.
+ *
+ * Returns { copied, skipped, conflicts }.
+ */
+export function copyTemplateTree(relativeSrcDir, destBaseDir, context = {}, options = {}) {
+    const {
+        force = false,
+        excludeDirs = [],
+        excludeFiles = [],
+        excludePaths = [],
+        manifest = null,
+        cwd = null,
+        source,
+        scaffold = false,
+        sync = false,
+        adopt = false,
+    } = options;
+
+    const srcRoot = join(TEMPLATES_DIR, relativeSrcDir);
+    if (!existsSync(srcRoot)) {
+        return { copied: 0, skipped: 0, conflicts: 0 };
+    }
+
+    let copied = 0;
+    let skipped = 0;
+    let conflicts = 0;
+
+    function walk(currentSrc, currentDest) {
+        for (const entry of readdirSync(currentSrc)) {
+            if (excludeDirs.includes(entry)) continue;
+
+            const srcPath = join(currentSrc, entry);
+            const relPath = relative(srcRoot, srcPath).split('\\').join('/');
+
+            if (excludePaths.includes(relPath)) continue;
+
+            const isEjs = entry.endsWith('.ejs');
+            const destName = isEjs ? entry.replace(/\.ejs$/, '') : entry;
+            const destPath = join(currentDest, destName);
+
+            if (statSync(srcPath).isDirectory()) {
+                ensureDir(destPath);
+                walk(srcPath, destPath);
+                continue;
+            }
+
+            if (excludeFiles.includes(entry)) continue;
+
+            const templateRel = join(relativeSrcDir, relPath).split('\\').join('/');
+
+            if (sync && manifest) {
+                const result = syncTemplate(templateRel, destPath, context, {
+                    render: isEjs,
+                    force,
+                    manifest,
+                    cwd,
+                    source,
+                    scaffold,
+                    adopt,
+                });
+                if (result.status === 'conflict') conflicts++;
+                else if (result.status === 'uptodate' || result.status === 'skipped') skipped++;
+                else copied++;
+                continue;
+            }
+
+            const result = copyTemplate(templateRel, destPath, context, {
+                force,
+                render: isEjs,
+            });
+
+            if (result.skipped) {
+                skipped++;
+            } else {
+                copied++;
+                if (manifest) {
+                    recordFile(manifest, cwd, destPath, result.content, { source, scaffold, template: templateRel });
+                }
+            }
+        }
+    }
+
+    ensureDir(destBaseDir);
+    walk(srcRoot, destBaseDir);
+    return { copied, skipped, conflicts };
+}

package/src/utils/gitignore.js

@@ -0,0 +1,26 @@
+import { existsSync, readFileSync, appendFileSync, mkdirSync } from 'fs';
+import { dirname } from 'path';
+
+/**
+ * Append entries to a .gitignore under a labelled header, skipping any that
+ * are already present. Idempotent: the header is written at most once.
+ */
+export function ensureGitignoreEntries(gitignorePath, paths, header) {
+    if (!paths.length) return;
+    const content = existsSync(gitignorePath) ? readFileSync(gitignorePath, 'utf8') : '';
+    const existing = new Set(content.split(/\r?\n/));
+    const toAdd = paths.filter((p) => !existing.has(p));
+    if (!toAdd.length) return;
+
+    let block = '';
+    if (header && !existing.has(header)) {
+        block += (content && !content.endsWith('\n') ? '\n' : '') + '\n' + header + '\n';
+    } else if (content && !content.endsWith('\n')) {
+        block += '\n';
+    }
+    block += toAdd.join('\n') + '\n';
+
+    const dir = dirname(gitignorePath);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    appendFileSync(gitignorePath, block);
+}

package/src/utils/logger.js

@@ -0,0 +1,9 @@
+import chalk from 'chalk';
+
+export const logger = {
+    info: (msg) => console.log(chalk.blue('info'), msg),
+    success: (msg) => console.log(chalk.green('✓'), msg),
+    warn: (msg) => console.log(chalk.yellow('⚠'), msg),
+    error: (msg) => console.log(chalk.red('✗'), msg),
+    skip: (msg) => console.log(chalk.gray('→'), chalk.gray(msg)),
+};

package/src/utils/manifest.js

@@ -0,0 +1,145 @@
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { dirname, isAbsolute, join, relative } from 'path';
+import { fileURLToPath } from 'url';
+import { createHash } from 'crypto';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+export const MANIFEST_NAME = '.shiftleft.json';
+
+/**
+ * Version of the installed shiftleft-tools package.
+ */
+export function getToolVersion() {
+    try {
+        const pkg = JSON.parse(readFileSync(join(__dirname, '../../package.json'), 'utf8'));
+        return pkg.version || '0.0.0';
+    } catch {
+        return '0.0.0';
+    }
+}
+
+export function manifestPath(cwd) {
+    return join(cwd, MANIFEST_NAME);
+}
+
+/**
+ * Normalize a path to a repo-root-relative, forward-slash manifest key.
+ * Accepts either an absolute path or an already-repo-relative path.
+ */
+export function manifestKey(cwd, target) {
+    const rel = isAbsolute(target) ? relative(cwd, target) : target;
+    return (rel || target).split('\\').join('/').replace(/^\.\//, '');
+}
+
+export function hashContent(content) {
+    return 'sha256:' + createHash('sha256').update(content, 'utf8').digest('hex');
+}
+
+export function loadManifest(cwd) {
+    const p = manifestPath(cwd);
+    if (!existsSync(p)) return null;
+    try {
+        const parsed = JSON.parse(readFileSync(p, 'utf8'));
+        parsed.managed = parsed.managed || {};
+        parsed.symlinks = parsed.symlinks || [];
+        return parsed;
+    } catch {
+        return null;
+    }
+}
+
+export function createManifest(stack) {
+    return {
+        toolVersion: getToolVersion(),
+        stack: stack || null,
+        managed: {},
+        symlinks: [],
+    };
+}
+
+export function saveManifest(cwd, manifest) {
+    manifest.toolVersion = manifest.toolVersion || getToolVersion();
+    writeFileSync(manifestPath(cwd), JSON.stringify(manifest, null, 2) + '\n', 'utf8');
+}
+
+/**
+ * Record the content the tool just wrote for a managed path.
+ * `relPath` may be absolute (resolved against cwd) or already repo-relative.
+ */
+export function recordFile(manifest, cwd, relPath, content, { source, scaffold = false, template } = {}) {
+    const key = manifestKey(cwd, relPath);
+    const entry = { hash: hashContent(content) };
+    entry.source = source || manifest.toolVersion || getToolVersion();
+    if (scaffold) entry.scaffold = true;
+    // Template source (relative to TEMPLATES_DIR) lets `doctor` recompute the
+    // upstream content for this file. Preserve a prior value if not supplied.
+    if (template) entry.template = template;
+    else if (manifest.managed[key]?.template) entry.template = manifest.managed[key].template;
+    manifest.managed[key] = entry;
+    return key;
+}
+
+/**
+ * Three-way comparison of a managed file.
+ *
+ *   current  = hash of the file on disk (null if missing)
+ *   recorded = hash the tool last wrote (from the manifest)
+ *   incoming = hash of the new template output (null if not provided)
+ *
+ * Returns one of: 'missing' | 'uptodate' | 'new' | 'clean' | 'local-edit'.
+ *
+ * Note: a file that exists on disk, differs from `incoming`, and was never
+ * recorded is treated as 'local-edit' (a conflict) rather than 'new', so the
+ * tool never silently clobbers a file it did not write.
+ */
+export function fileState(cwd, relPath, manifest, incomingContent) {
+    const key = manifestKey(cwd, relPath);
+    const abs = join(cwd, key);
+
+    const recorded = manifest?.managed?.[key]?.hash ?? null;
+    const current = existsSync(abs) ? hashContent(readFileSync(abs, 'utf8')) : null;
+    const incoming = incomingContent != null ? hashContent(incomingContent) : null;
+
+    if (current === null) {
+        return recorded === null ? 'new' : 'missing';
+    }
+    if (incoming !== null && current === incoming) {
+        return 'uptodate';
+    }
+    if (recorded === null) {
+        // On disk, diverges from incoming, never managed by us -> don't clobber.
+        return 'local-edit';
+    }
+    if (current === recorded) {
+        return 'clean';
+    }
+    return 'local-edit';
+}
+
+export function isScaffold(manifest, cwd, relPath) {
+    const key = manifestKey(cwd, relPath);
+    return manifest?.managed?.[key]?.scaffold === true;
+}
+
+/**
+ * Library-script paths (relative to postman/scripts/) the repo owns. stageScripts
+ * leaves these in place instead of overwriting them from the package — for repos
+ * that customize a library script (e.g. a service-specific runners/run-tests-local.sh).
+ */
+export function getProtectedPaths(manifest) {
+    return manifest && Array.isArray(manifest.protected) ? manifest.protected : [];
+}
+
+/**
+ * Normalize a user-supplied protected path to the postman/scripts-relative,
+ * forward-slash form stored in the manifest (and matched by stageScripts excludes).
+ */
+export function normalizeScriptPath(p) {
+    return p
+        .split('\\').join('/')
+        .replace(/^\.?\//, '')
+        .replace(/^postman\/scripts\//, '')
+        .replace(/\/+$/, '');
+}

package/src/utils/stack.js

@@ -0,0 +1,80 @@
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Files in the base `postman/scripts` tree that the Node overlay
+ * (`postman-node/scripts`) replaces or that don't apply to Node. Excluded from
+ * the base copy so only the overlay writes them (avoids double-writes that make
+ * a clean repo perpetually report drift). Shared by init-postman and update.
+ */
+export const NODE_BASE_SCRIPT_EXCLUDES = [
+    'run-all.sh',
+    'runners/run-tests-local.sh',
+    'runners/run-tests-staging.sh',
+    'infra/start-mocks.sh',
+    'infra/stop-mocks.sh',
+    'report-generators/java-api-coverage-matrix.sh',
+    'report-generators/mutation-report.sh',
+    'report-generators/stage-report-artifacts.sh',
+];
+
+/**
+ * Build the EJS render context for a service. Shared by init-postman and
+ * update so that templates needing `serviceName` render consistently.
+ */
+export function buildContext(serviceName, stack, includeStaging = false) {
+    const name = serviceName || 'service';
+    return {
+        serviceName: name,
+        serviceDisplayName: name.replace(/-/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase()),
+        serviceNameUpper: name.toUpperCase().replace(/-/g, '_'),
+        serviceNameLower: name.toLowerCase().replace(/-/g, '_'),
+        includeStaging,
+        stack,
+    };
+}
+
+/**
+ * Detect project stack from cwd or explicit --stack option.
+ * @param {string} cwd
+ * @param {'java'|'node'|undefined} explicit
+ * @returns {'java'|'node'|null}
+ */
+export function detectStack(cwd, explicit) {
+    if (explicit === 'java' || explicit === 'node') {
+        return explicit;
+    }
+
+    const hasPom = existsSync(join(cwd, 'pom.xml'));
+    const hasPkg = existsSync(join(cwd, 'package.json'));
+
+    if (hasPom) return 'java';
+    if (hasPkg) return 'node';
+    return null;
+}
+
+/**
+ * Infer service name from pom.xml or package.json.
+ */
+export function inferServiceName(cwd) {
+    const pomPath = join(cwd, 'pom.xml');
+    if (existsSync(pomPath)) {
+        const pom = readFileSync(pomPath, 'utf8');
+        const match = pom.match(/<artifactId>([^<]+)<\/artifactId>/);
+        if (match) return match[1];
+    }
+
+    const pkgPath = join(cwd, 'package.json');
+    if (existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+            if (pkg.name) {
+                return pkg.name.replace(/^@[^/]+\//, '').replace(/_/g, '-');
+            }
+        } catch {
+            // ignore parse errors
+        }
+    }
+
+    return null;
+}