UNPKG

@augmentcode/ag-redux-toolkit

Version:

Redux + Saga state management for Svelte apps — designed for AI agents. Includes runtime TypeScript source, AI skills, and reference documentation for robust, observable, high-performance state management.

421 lines (352 loc) • 14.6 kB
#!/usr/bin/env node /** * install-skills helper — copies packaged AI skills into a target project. * * Safety guarantees: * - Writes only under the consumer project root's .agents/skills/ag-redux-toolkit/ directory * - Refreshes a previous install first using the installed-skills.yml manifest * - Preserves user-authored files that are not listed in the manifest * - Removes package-owned copies left in the legacy flat .agents/skills/ location * - Excludes generated skills/_artifacts content * - No-op when run outside node_modules (e.g. during the package's own npm install) * - Never crashes — logs warnings and exits 0 */ import { copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync, rmdirSync, writeFileSync, } from "node:fs"; import { dirname, isAbsolute, relative, resolve, sep } from "node:path"; import { fileURLToPath, pathToFileURL } from "node:url"; const __dirname = dirname(fileURLToPath(import.meta.url)); export const defaultPackageRoot = resolve(__dirname, ".."); export const skillInstallDirName = "ag-redux-toolkit"; export const installedSkillsManifestFileName = "installed-skills.yml"; export const legacyPackageSkillNames = [ "svelte-redux-toolkit", "init-svelte-redux-toolkit", "migrate-to-svelte-redux-toolkit", ]; export const skillInstallBundles = { all: undefined, core: ["SKILL.md", "setup", "core"], react: ["SKILL.md", "setup", "core", "react"], streaming: ["SKILL.md", "setup", "core", "streaming"], svelte: ["SKILL.md", "setup", "core", "svelte"], }; export const supportedSkillInstallTargets = Object.keys(skillInstallBundles); export function normalizeSkillInstallTarget(skillInstallTarget = "all") { if (supportedSkillInstallTargets.includes(skillInstallTarget)) return skillInstallTarget; throw new Error(`Unsupported install-skills target: ${skillInstallTarget}`); } export function getPackageOwnedSkillNames(skillNames, { includeLegacy = true } = {}) { return [...new Set(includeLegacy ? [...skillNames, ...legacyPackageSkillNames] : skillNames)]; } export function isSameOrChild(parent, child) { const relativePath = relative(parent, child); return relativePath === "" || (!relativePath.startsWith("..") && !isAbsolute(relativePath)); } function hasNodeModulesSegment(path) { return resolve(path).split(sep).includes("node_modules"); } function nearestNodeModulesOwner(path) { const segments = resolve(path).split(sep); const nodeModulesIndex = segments.lastIndexOf("node_modules"); return nodeModulesIndex > 0 ? segments.slice(0, nodeModulesIndex).join(sep) : undefined; } export function findConsumerProjectRoot({ packageRoot = defaultPackageRoot, env = process.env } = {}) { const resolvedPackageRoot = resolve(packageRoot); const initCwd = env.INIT_CWD ? resolve(env.INIT_CWD) : undefined; if (initCwd && isSameOrChild(initCwd, resolvedPackageRoot) && hasNodeModulesSegment(relative(initCwd, resolvedPackageRoot))) { return initCwd; } return nearestNodeModulesOwner(resolvedPackageRoot); } export function isGeneratedSkillArtifact(path, skillsRoot) { const relativePath = relative(skillsRoot, path); return relativePath === "_artifacts" || relativePath.startsWith(`_artifacts${sep}`); } function safeResolveChild(parent, ...segments) { const resolvedParent = resolve(parent); const child = resolve(resolvedParent, ...segments); if (!isSameOrChild(resolvedParent, child)) { throw new Error(`Refusing to write outside ${resolvedParent}`); } return child; } export function getPackagedSkillInventory(skillsRoot) { const files = new Map(); const skillNames = []; function collect(currentPath) { if (isGeneratedSkillArtifact(currentPath, skillsRoot)) return; const stat = lstatSync(currentPath); if (stat.isDirectory() && !stat.isSymbolicLink()) { for (const entry of readdirSync(currentPath)) { collect(resolve(currentPath, entry)); } return; } if (stat.isFile()) { files.set(relative(skillsRoot, currentPath), currentPath); } } for (const entry of readdirSync(skillsRoot)) { const entryPath = resolve(skillsRoot, entry); if (isGeneratedSkillArtifact(entryPath, skillsRoot)) continue; skillNames.push(entry); collect(entryPath); } return { files, skillNames }; } function readPackageMetadata(packageRoot) { try { const packageJson = JSON.parse(readFileSync(resolve(packageRoot, "package.json"), "utf8")); return { name: typeof packageJson.name === "string" ? packageJson.name : "ag-redux-toolkit", version: typeof packageJson.version === "string" ? packageJson.version : "0.0.0", }; } catch { return { name: "ag-redux-toolkit", version: "0.0.0" }; } } function toPosixPath(relativePath) { return relativePath.split(sep).join("/"); } function parseYamlScalar(value) { if (value.startsWith('"')) return JSON.parse(value); return value; } export function serializeInstalledSkillsManifest(manifest) { const lines = [ `package: ${JSON.stringify(manifest.package)}`, `version: ${JSON.stringify(manifest.version)}`, `target: ${JSON.stringify(manifest.target)}`, `installedAt: ${JSON.stringify(manifest.installedAt)}`, "files:", ...manifest.files.map((relativePath) => ` - ${JSON.stringify(relativePath)}`), ]; return `${lines.join("\n")}\n`; } export function parseInstalledSkillsManifest(text) { const manifest = { files: [] }; let inFiles = false; for (const rawLine of text.split(/\r?\n/)) { const line = rawLine.trimEnd(); if (!line || line.trimStart().startsWith("#")) continue; const listItem = /^\s+-\s*(.+)$/.exec(line); if (inFiles && listItem) { const entry = parseYamlScalar(listItem[1]); if (typeof entry !== "string" || entry === "") throw new Error(`Invalid manifest file entry: ${line}`); manifest.files.push(entry); continue; } const keyValue = /^([A-Za-z][\w-]*):\s*(.*)$/.exec(line); if (!keyValue) throw new Error(`Invalid manifest line: ${line}`); const [, key, value] = keyValue; inFiles = key === "files" && value === ""; if (value !== "") manifest[key] = parseYamlScalar(value); } if (!Array.isArray(manifest.files) || manifest.files.some((entry) => typeof entry !== "string")) { throw new Error("Manifest files list is invalid"); } return manifest; } export function readInstalledSkillsManifest(manifestPath, { logger = console } = {}) { if (!existsSync(manifestPath)) return undefined; try { return parseInstalledSkillsManifest(readFileSync(manifestPath, "utf8")); } catch (err) { logger.warn( `[ag-redux-toolkit] ignoring unreadable ${installedSkillsManifestFileName} manifest (${err.message}); previously installed files will not be refreshed.` ); return undefined; } } export function removeInstalledManifestFiles({ installDest, files = [], logger = console } = {}) { const resolvedInstallDest = resolve(installDest); let removed = 0; const candidateDirs = new Set(); for (const relativePath of files) { let target; try { target = safeResolveChild(resolvedInstallDest, ...relativePath.split("/")); } catch { logger.warn(`[ag-redux-toolkit] skipping unsafe manifest entry: ${relativePath}`); continue; } if (target === resolvedInstallDest) continue; if (existsSync(target) && lstatSync(target).isFile()) { rmSync(target, { force: true }); removed += 1; } for (let dir = dirname(target); dir !== resolvedInstallDest && isSameOrChild(resolvedInstallDest, dir); dir = dirname(dir)) { candidateDirs.add(dir); } } let pruned = 0; for (const dir of [...candidateDirs].sort((left, right) => right.length - left.length)) { if (existsSync(dir) && readdirSync(dir).length === 0) { rmdirSync(dir); pruned += 1; } } return { removed, pruned }; } export function removeLegacyFlatSkillCopies({ skillsSrc, legacySkillsDest } = {}) { if (!existsSync(skillsSrc) || !existsSync(legacySkillsDest)) return { removed: 0, pruned: 0 }; const inventory = getPackagedSkillInventory(skillsSrc); const legacySkillNames = getPackageOwnedSkillNames(inventory.skillNames).filter( (skillName) => skillName !== skillInstallDirName ); return removePackageOwnedSkillCopies({ skillsDest: legacySkillsDest, packagedFiles: inventory.files, skillNames: legacySkillNames, removeCurrent: true, }); } function isSelectedSkillPath(relativePath, skillNames) { return skillNames.some((skillName) => relativePath === skillName || relativePath.startsWith(`${skillName}${sep}`)); } export function selectPackagedSkillInventory(inventory, skillInstallTarget = "all") { const resolvedSkillInstallTarget = normalizeSkillInstallTarget(skillInstallTarget); const selectedSkillNames = skillInstallBundles[resolvedSkillInstallTarget]; if (!selectedSkillNames) return inventory; return { files: new Map([...inventory.files].filter(([relativePath]) => isSelectedSkillPath(relativePath, selectedSkillNames))), skillNames: inventory.skillNames.filter((skillName) => selectedSkillNames.includes(skillName)), }; } function filesAreEqual(left, right) { if (!existsSync(right)) return false; const rightStat = lstatSync(right); if (!rightStat.isFile()) return false; return readFileSync(left).equals(readFileSync(right)); } export function removePackageOwnedSkillCopies({ skillsDest, packagedFiles, skillNames, removeCurrent = false } = {}) { if (!existsSync(skillsDest)) return { removed: 0, pruned: 0 }; let removed = 0; let pruned = 0; function clean(currentPath) { const relativePath = relative(skillsDest, currentPath); if (relativePath.startsWith("..") || isAbsolute(relativePath)) return; const stat = lstatSync(currentPath); if (stat.isDirectory() && !stat.isSymbolicLink()) { for (const entry of readdirSync(currentPath)) { clean(resolve(currentPath, entry)); } if (readdirSync(currentPath).length === 0) { rmdirSync(currentPath); pruned += 1; } return; } if (removeCurrent || !packagedFiles.has(relativePath)) { rmSync(currentPath, { force: true }); removed += 1; } } for (const skillName of skillNames) { const skillDest = safeResolveChild(skillsDest, skillName); if (existsSync(skillDest)) clean(skillDest); } return { removed, pruned }; } export function copyPackagedSkillsToProject({ packageRoot = defaultPackageRoot, projectRoot, logger = console, skillInstallTarget = "all", } = {}) { const resolvedSkillInstallTarget = normalizeSkillInstallTarget(skillInstallTarget); const resolvedProjectRoot = projectRoot ?? findConsumerProjectRoot({ packageRoot }); if (!resolvedProjectRoot) { logger.log( "[ag-redux-toolkit] install-skills skipped: package is not installed under a consumer node_modules directory; no skill files were copied." ); return { installed: false, skipped: true, reason: "not-installed-dependency" }; } const skillsSrc = resolve(packageRoot, "skills"); if (!existsSync(skillsSrc)) { logger.log("[ag-redux-toolkit] install-skills skipped: packaged skills were not found; no skill files were copied."); return { installed: false, skipped: true, reason: "missing-skills", projectRoot: resolvedProjectRoot }; } const legacySkillsDest = safeResolveChild(resolvedProjectRoot, ".agents", "skills"); const installDest = safeResolveChild(legacySkillsDest, skillInstallDirName); const manifestPath = safeResolveChild(installDest, installedSkillsManifestFileName); const inventory = selectPackagedSkillInventory(getPackagedSkillInventory(skillsSrc), resolvedSkillInstallTarget); mkdirSync(installDest, { recursive: true }); const nextFiles = new Set([...inventory.files.keys()].map(toPosixPath)); const previousManifest = readInstalledSkillsManifest(manifestPath, { logger }); const staleFiles = (previousManifest?.files ?? []).filter((relativePath) => !nextFiles.has(relativePath)); const refresh = removeInstalledManifestFiles({ installDest, files: staleFiles, logger }); const legacy = removeLegacyFlatSkillCopies({ skillsSrc, legacySkillsDest }); let copied = 0; let updated = 0; let unchanged = 0; for (const [relativePath, sourcePath] of inventory.files) { const destPath = safeResolveChild(installDest, relativePath); mkdirSync(dirname(destPath), { recursive: true }); if (filesAreEqual(sourcePath, destPath)) { unchanged += 1; continue; } const existed = existsSync(destPath); if (existed) rmSync(destPath, { recursive: true, force: true }); copyFileSync(sourcePath, destPath); if (existed) updated += 1; else copied += 1; } const packageMetadata = readPackageMetadata(packageRoot); const manifest = { package: packageMetadata.name, version: packageMetadata.version, target: resolvedSkillInstallTarget, installedAt: new Date().toISOString(), files: [...inventory.files.keys()].map(toPosixPath).sort(), }; writeFileSync(manifestPath, serializeInstalledSkillsManifest(manifest)); const removed = refresh.removed + legacy.removed; const pruned = refresh.pruned + legacy.pruned; const commandLabel = resolvedSkillInstallTarget === "all" ? "install-skills" : `install-skills:${resolvedSkillInstallTarget}`; logger.log( `[ag-redux-toolkit] ${commandLabel} copied packaged skills to .agents/skills/ag-redux-toolkit/ (${copied} copied, ${updated} updated, ${unchanged} unchanged, ${removed} stale removed, ${pruned} empty dirs pruned).` ); return { installed: copied > 0 || updated > 0, skipped: copied === 0 && updated === 0 && removed === 0 && pruned === 0, projectRoot: resolvedProjectRoot, destination: installDest, manifestPath, copied, updated, unchanged, removed, pruned, skillInstallTarget: resolvedSkillInstallTarget, }; } export function installIntentSkillGuidance({ packageRoot = defaultPackageRoot, projectRoot, env = process.env, logger = console, skillInstallTarget = "all", } = {}) { const resolvedProjectRoot = projectRoot ?? findConsumerProjectRoot({ packageRoot, env }); return copyPackagedSkillsToProject({ packageRoot, projectRoot: resolvedProjectRoot, logger, skillInstallTarget }); } if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) { try { installIntentSkillGuidance(); } catch (err) { console.warn(`[ag-redux-toolkit] install-skills warning: ${err.message}`); process.exit(0); } }