@rbbtsn0w/adg 0.1.0-alpha.1 → 0.1.0-beta.2

package/dist/vendor/skills/src/frontmatter.js

@@ -0,0 +1,13 @@
+import { parse as parseYaml } from 'yaml';
+/**
+ * Minimal frontmatter parser. Only supports YAML (the `---` delimiter).
+ * Does NOT support `---js` / `---javascript` to avoid eval()-based RCE
+ * that exists in gray-matter's built-in JS engine.
+ */
+export function parseFrontmatter(raw) {
+    const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+    if (!match)
+        return { data: {}, content: raw };
+    const data = parseYaml(match[1]) ?? {};
+    return { data, content: match[2] ?? '' };
+}

package/dist/vendor/skills/src/git-tree.js

@@ -0,0 +1,32 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+/**
+ * ADG-added file (see vendor/skills/PROVENANCE.md → Local patches).
+ *
+ * Return the git *tree object SHA* for a folder inside a freshly cloned repo —
+ * the SAME 40-hex value GitHub's Trees API returns and that
+ * `getSkillFolderHashFromTree` (blob.ts) compares against at update time.
+ *
+ * Used by `add.ts` so a github source that fell back to a `git clone` at install
+ * still records a tree SHA, not a sha256 content hash. Otherwise the install and
+ * update hashing schemes diverge and every update perpetually re-flags the skill
+ * (the bug that made a collection repo "fully update" on every run).
+ *
+ * `folder === ''` means the repo root. Returns null if git can't resolve it.
+ *
+ * Deliberately uses `child_process` rather than simple-git: this keeps the file
+ * free of simple-git's typings, which don't satisfy ADG's strict tsconfig when a
+ * test pulls the module into the typecheck graph.
+ */
+export async function gitTreeShaForFolder(repoDir, folder) {
+    const spec = folder ? `HEAD:${folder}` : 'HEAD^{tree}';
+    try {
+        const { stdout } = await execFileAsync('git', ['-C', repoDir, 'rev-parse', spec]);
+        const sha = stdout.trim();
+        return /^[0-9a-f]{40}$/.test(sha) ? sha : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/vendor/skills/src/git.js

@@ -0,0 +1,235 @@
+// ADG patch: named import. The default import is not callable under the root
+// tsconfig (NodeNext + verbatimModuleSyntax, no esModuleInterop); simple-git
+// exposes `simpleGit` as a named export. See vendor/skills/PROVENANCE.md.
+import { simpleGit } from 'simple-git';
+import { join, normalize, resolve, sep } from 'path';
+import { mkdtemp, mkdir, rm } from 'fs/promises';
+import { tmpdir } from 'os';
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+const DEFAULT_CLONE_TIMEOUT_MS = 300_000; // 5 minutes
+const CLONE_TIMEOUT_MS = (() => {
+    const raw = process.env.SKILLS_CLONE_TIMEOUT_MS;
+    if (!raw)
+        return DEFAULT_CLONE_TIMEOUT_MS;
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_CLONE_TIMEOUT_MS;
+})();
+const execFileAsync = promisify(execFile);
+export class GitCloneError extends Error {
+    url;
+    isTimeout;
+    isAuthError;
+    constructor(message, url, isTimeout = false, isAuthError = false) {
+        super(message);
+        this.name = 'GitCloneError';
+        this.url = url;
+        this.isTimeout = isTimeout;
+        this.isAuthError = isAuthError;
+    }
+}
+export function parseGitHubRepoUrl(url) {
+    const sshMatch = url.match(/^git@github\.com:([^/]+)\/([^/]+?)(?:\.git)?$/i);
+    if (sshMatch) {
+        const owner = sshMatch[1];
+        const repo = sshMatch[2];
+        return {
+            owner,
+            repo,
+            slug: `${owner}/${repo}`,
+            sshUrl: `git@github.com:${owner}/${repo}.git`,
+        };
+    }
+    try {
+        const parsed = new URL(url);
+        if (parsed.hostname !== 'github.com')
+            return null;
+        const match = parsed.pathname.match(/^\/([^/]+)\/([^/]+?)(?:\.git)?\/?$/);
+        if (!match)
+            return null;
+        const owner = match[1];
+        const repo = match[2];
+        return {
+            owner,
+            repo,
+            slug: `${owner}/${repo}`,
+            sshUrl: `git@github.com:${owner}/${repo}.git`,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function isGitHubHttpsCloneUrl(url) {
+    try {
+        const parsed = new URL(url);
+        return parsed.protocol === 'https:' && parsed.hostname === 'github.com';
+    }
+    catch {
+        return false;
+    }
+}
+export function isGitHubSsoAuthError(message) {
+    const lower = message.toLowerCase();
+    return (lower.includes('saml sso') ||
+        lower.includes('enforced sso') ||
+        lower.includes('enabled or enforced saml') ||
+        lower.includes('re-authorize the oauth application'));
+}
+function isAuthFailure(message) {
+    return (message.includes('Authentication failed') ||
+        message.includes('could not read Username') ||
+        message.includes('Permission denied') ||
+        message.includes('Repository not found') ||
+        message.includes('requested URL returned error: 403') ||
+        isGitHubSsoAuthError(message));
+}
+function createGitClient(extraEnv) {
+    return simpleGit({
+        timeout: { block: CLONE_TIMEOUT_MS },
+        // When git-lfs is NOT installed, GIT_LFS_SKIP_SMUDGE has no effect —
+        // git sees `filter=lfs` in .gitattributes, tries to run
+        // `git-lfs filter-process`, and aborts the checkout with:
+        //   git-lfs filter-process: git-lfs: command not found
+        //   fatal: the remote end hung up unexpectedly
+        //   warning: Clone succeeded, but checkout failed.
+        // Overriding filter.lfs.* at the command level disables the filter
+        // entirely for this clone, so checkout succeeds regardless of whether
+        // git-lfs is installed. LFS-tracked files are left as ~130-byte
+        // pointer files, which the skills installer doesn't read anyway
+        // (skills are plain text — HTML/MD/JSON — never LFS-tracked).
+        //
+        // Reported downstream: heygen-com/hyperframes#407.
+        config: [
+            'filter.lfs.required=false',
+            'filter.lfs.smudge=',
+            'filter.lfs.clean=',
+            'filter.lfs.process=',
+        ],
+        // ADG patch: simple-git >=3.36 blocks `filter.*.smudge/clean` configs (an RCE
+        // vector via a malicious filter command) unless explicitly allowed, failing
+        // every clone with "Configuring filter.smudge is not permitted without
+        // enabling allowUnsafeFilter". Here the filters are set to EMPTY — we are
+        // *disabling* the LFS filter, not running one — so opting in is safe and is
+        // exactly the intent of the config above. See vendor/skills/PROVENANCE.md.
+        unsafe: {
+            allowUnsafeFilter: true,
+        },
+        // ADG patch: env must be applied via `.env()`, not as a constructor option.
+        // simple-git's factory only reads baseDir/maxConcurrentProcesses/trimmed from
+        // the options object and silently drops `env`, so the GIT_TERMINAL_PROMPT /
+        // GIT_LFS_SKIP_SMUDGE / GIT_SSH_COMMAND overrides below never reached the
+        // spawned git before this. See vendor/skills/PROVENANCE.md.
+    }).env({
+        ...process.env,
+        GIT_TERMINAL_PROMPT: '0',
+        // When git-lfs IS installed, tell it not to download LFS content during
+        // checkout. See #952 for context and empirical impact.
+        GIT_LFS_SKIP_SMUDGE: '1',
+        ...extraEnv,
+    });
+}
+async function resetTempDir(dir) {
+    await rm(dir, { recursive: true, force: true }).catch(() => { });
+    await mkdir(dir, { recursive: true });
+}
+async function tryGhClone(repo, tempDir, ref) {
+    let cloneTarget = repo.slug;
+    try {
+        const { stdout, stderr } = await execFileAsync('gh', ['auth', 'status', '-h', 'github.com'], {
+            timeout: 5000,
+            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+        });
+        const statusOutput = `${stdout}${stderr}`;
+        if (/Git operations protocol:\s+ssh/i.test(statusOutput)) {
+            cloneTarget = repo.sshUrl;
+        }
+    }
+    catch {
+        return false;
+    }
+    const gitFlags = ref ? ['--depth=1', '--branch', ref] : ['--depth=1'];
+    await execFileAsync('gh', ['repo', 'clone', cloneTarget, tempDir, '--', ...gitFlags], {
+        timeout: CLONE_TIMEOUT_MS,
+        env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+    });
+    return true;
+}
+function buildGitHubAuthError(url, repo, message) {
+    if (repo && isGitHubSsoAuthError(message)) {
+        return (`GitHub blocked HTTPS access to ${url} because the organization enforces SAML SSO.\n` +
+            `  skills tried your existing git credentials and available fallbacks, but none succeeded.\n` +
+            `  - Re-authorize your GitHub credentials/app for that org's SSO policy\n` +
+            `  - Or rerun with SSH: npx skills add ${repo.sshUrl}\n` +
+            `  - Verify access with: gh auth status -h github.com or ssh -T git@github.com`);
+    }
+    if (repo) {
+        return (`Authentication failed for ${url}.\n` +
+            `  - For private repos, ensure you have access\n` +
+            `  - Retry with SSH: npx skills add ${repo.sshUrl}\n` +
+            `  - Check access with: gh auth status -h github.com or ssh -T git@github.com`);
+    }
+    return (`Authentication failed for ${url}.\n` +
+        `  - For private repos, ensure you have access\n` +
+        `  - For SSH: Check your keys with 'ssh -T git@github.com'\n` +
+        `  - For HTTPS: Run 'gh auth login' or configure git credentials`);
+}
+export async function cloneRepo(url, ref) {
+    const tempDir = await mkdtemp(join(tmpdir(), 'skills-'));
+    const cloneOptions = ref ? ['--depth', '1', '--branch', ref] : ['--depth', '1'];
+    const repo = parseGitHubRepoUrl(url);
+    try {
+        await createGitClient().clone(url, tempDir, cloneOptions);
+        return tempDir;
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        const isTimeout = errorMessage.includes('block timeout') || errorMessage.includes('timed out');
+        const isAuthError = isAuthFailure(errorMessage);
+        if (isTimeout) {
+            await rm(tempDir, { recursive: true, force: true }).catch(() => { });
+            const seconds = Math.round(CLONE_TIMEOUT_MS / 1000);
+            throw new GitCloneError(`Clone timed out after ${seconds}s. Common causes:\n` +
+                `  - Large repository: raise the timeout with SKILLS_CLONE_TIMEOUT_MS=600000 (10m)\n` +
+                `  - Slow network: retry, or clone manually and pass the local path to 'skills add'\n` +
+                `  - Private repo without credentials: ensure auth is configured\n` +
+                `      - For SSH: ssh-add -l (to check loaded keys)\n` +
+                `      - For HTTPS: gh auth status (if using GitHub CLI)`, url, true, false);
+        }
+        if (isAuthError && repo && isGitHubHttpsCloneUrl(url)) {
+            try {
+                await resetTempDir(tempDir);
+                if (await tryGhClone(repo, tempDir, ref)) {
+                    return tempDir;
+                }
+            }
+            catch {
+                // Fall through to SSH retry.
+            }
+            try {
+                await resetTempDir(tempDir);
+                await createGitClient({
+                    GIT_SSH_COMMAND: process.env.GIT_SSH_COMMAND ?? 'ssh -o BatchMode=yes',
+                }).clone(repo.sshUrl, tempDir, cloneOptions);
+                return tempDir;
+            }
+            catch {
+                // Fall through to the targeted auth error below.
+            }
+        }
+        await rm(tempDir, { recursive: true, force: true }).catch(() => { });
+        if (isAuthError) {
+            throw new GitCloneError(buildGitHubAuthError(url, repo, errorMessage), url, false, true);
+        }
+        throw new GitCloneError(`Failed to clone ${url}: ${errorMessage}`, url, false, false);
+    }
+}
+export async function cleanupTempDir(dir) {
+    // Validate that the directory path is within tmpdir to prevent deletion of arbitrary paths
+    const normalizedDir = normalize(resolve(dir));
+    const normalizedTmpDir = normalize(resolve(tmpdir()));
+    if (!normalizedDir.startsWith(normalizedTmpDir + sep) && normalizedDir !== normalizedTmpDir) {
+        throw new Error('Attempted to clean up directory outside of temp directory');
+    }
+    await rm(dir, { recursive: true, force: true });
+}

package/dist/vendor/skills/src/install.js

@@ -0,0 +1,75 @@
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import { readLocalLock } from "./local-lock.js";
+import { runAdd } from "./add.js";
+import { runSync, parseSyncOptions } from "./sync.js";
+import { getUniversalAgents } from "./agents.js";
+/**
+ * Install all skills from the local skills-lock.json.
+ * Groups skills by source and calls `runAdd` for each group.
+ *
+ * Only installs to .agents/skills/ (universal agents) -- the canonical
+ * project-level location. Does not install to agent-specific directories.
+ *
+ * node_modules skills are handled via experimental_sync.
+ */
+export async function runInstallFromLock(args) {
+    const cwd = process.cwd();
+    const lock = await readLocalLock(cwd);
+    const skillEntries = Object.entries(lock.skills);
+    if (skillEntries.length === 0) {
+        p.log.warn('No project skills found in skills-lock.json');
+        p.log.info(`Add project-level skills with ${pc.cyan('npx skills add <package>')} (without ${pc.cyan('-g')})`);
+        return;
+    }
+    // Only install to .agents/skills/ (universal agents)
+    const universalAgentNames = getUniversalAgents();
+    // Separate node_modules skills from remote skills
+    const nodeModuleSkills = [];
+    const bySource = new Map();
+    for (const [skillName, entry] of skillEntries) {
+        if (entry.sourceType === 'node_modules') {
+            nodeModuleSkills.push(skillName);
+            continue;
+        }
+        const installSource = entry.ref ? `${entry.source}#${entry.ref}` : entry.source;
+        const existing = bySource.get(installSource);
+        if (existing) {
+            existing.skills.push(skillName);
+        }
+        else {
+            bySource.set(installSource, {
+                sourceType: entry.sourceType,
+                skills: [skillName],
+            });
+        }
+    }
+    const remoteCount = skillEntries.length - nodeModuleSkills.length;
+    if (remoteCount > 0) {
+        p.log.info(`Restoring ${pc.cyan(String(remoteCount))} skill${remoteCount !== 1 ? 's' : ''} from skills-lock.json into ${pc.dim('.agents/skills/')}`);
+    }
+    // Install remote skills grouped by source
+    for (const [source, { skills }] of bySource) {
+        try {
+            await runAdd([source], {
+                skill: skills,
+                agent: universalAgentNames,
+                yes: true,
+            });
+        }
+        catch (error) {
+            p.log.error(`Failed to install from ${pc.cyan(source)}: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    // Handle node_modules skills via sync
+    if (nodeModuleSkills.length > 0) {
+        p.log.info(`${pc.cyan(String(nodeModuleSkills.length))} skill${nodeModuleSkills.length !== 1 ? 's' : ''} from node_modules`);
+        try {
+            const { options: syncOptions } = parseSyncOptions(args);
+            await runSync(args, { ...syncOptions, yes: true, agent: universalAgentNames });
+        }
+        catch (error) {
+            p.log.error(`Failed to sync node_modules skills: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+}