promptlings 0.1.0-alpha.1 → 0.1.0-alpha.2

package/bin/promptlings.js

@@ -59,7 +59,7 @@ async function main() {
   const runAddMcp = (args) => runPackage("add-mcp", args);
   const temporary = mkdtempSync(join(tmpdir(), "promptlings-"));
   try {
-    if (steps.tools) (await import("../lib/tools.js")).installTools(options, temporary, runSkills);
+    if (steps.tools) await (await import("../lib/tools.js")).installTools(options, temporary);
     if (steps.publish) publish(options, temporary);
     if (steps.memory) await (await import("../lib/memory.js")).installMemory(options, { runSkills, runAddMcp });
   } finally {

package/lib/run.js

@@ -1,4 +1,4 @@
-import { spawnSync } from "node:child_process";
+import { spawn as spawnAsync, spawnSync } from "node:child_process";
 import { existsSync, lstatSync, readFileSync } from "node:fs";
 import { delimiter, dirname, extname, join } from "node:path";
 import { createRequire } from "node:module";
@@ -37,7 +37,7 @@ function spawn(command, args, options = {}) {
     cwd: options.cwd,
     env: options.env || process.env,
     encoding: "utf8",
-    stdio: options.capture ? ["inherit", "pipe", "inherit"] : "inherit",
+    stdio: options.capture ? ["inherit", "pipe", options.silent ? "pipe" : "inherit"] : "inherit",
     maxBuffer: 64 * 1024 * 1024,
   };
   if (windows && /\.(cmd|bat)$/i.test(resolved)) {
@@ -56,6 +56,18 @@ export function run(command, args = [], options = {}) {
   return result;
 }
 
+// Runs an executable concurrently with others, collecting stdout and stderr together so the caller can print them in order.
+export function runBuffered(executable, args = [], options = {}) {
+  return new Promise((resolve) => {
+    let output = "";
+    const child = spawnAsync(executable, args, { cwd: options.cwd, env: options.env || process.env, stdio: ["ignore", "pipe", "pipe"] });
+    child.stdout.on("data", (chunk) => { output += chunk; });
+    child.stderr.on("data", (chunk) => { output += chunk; });
+    child.on("error", (error) => resolve({ status: null, output: `${output}${error.message}\n` }));
+    child.on("close", (status) => resolve({ status, output }));
+  });
+}
+
 export const capture = (command, args = [], options = {}) =>
   run(command, args, { ...options, capture: true }).stdout.trim();
 

package/lib/tools.js

@@ -1,42 +1,74 @@
-import { accessSync, appendFileSync, constants, existsSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
+import { spawnSync } from "node:child_process";
+import { accessSync, appendFileSync, constants, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { pins } from "./pins.js";
-import { capture, fail, powershell, prependPath, run, succeeds, which, windows } from "./run.js";
+import { capture, fail, packageBin, powershell, prependPath, run, runBuffered, succeeds, which, windows } from "./run.js";
 
 // WinGet reports an already-current package as "no applicable update". Node may surface it unsigned.
 const wingetCurrent = [0, -1978335189, 2316632107];
 
+// First string value printed by `reg query`, with %VARIABLE% references expanded from the environment.
+export function regString(output, env = process.env) {
+  const value = /^\s+.+?\s{4}REG_(?:EXPAND_)?SZ\s{4}(.*)$/m.exec(output ?? "")?.[1]?.trim();
+  return value ? value.replace(/%([^%]+)%/g, (whole, name) => env[name] ?? whole) : null;
+}
+
+const regQuery = (key, args) => {
+  const result = spawnSync("reg", ["query", key, ...args], { encoding: "utf8", windowsHide: true });
+  return result.status === 0 ? regString(result.stdout) : null;
+};
+
 function refreshWindowsPath() {
-  const persisted = powershell(
-    '[Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [Environment]::GetEnvironmentVariable("Path","User")',
-    { capture: true },
-  ).stdout.trim();
-  prependPath(...persisted.split(";"));
+  const machine = regQuery("HKLM\\SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Environment", ["/v", "Path"]);
+  const user = regQuery("HKCU\\Environment", ["/v", "Path"]);
+  prependPath(...[machine, user].filter(Boolean).join(";").split(";"));
 }
 
 // Document rendering needs either Microsoft Word or LibreOffice.
 function windowsWordPath() {
-  const script = `foreach ($hive in "HKLM:", "HKCU:") {
-  $path = (Get-ItemProperty -LiteralPath "$hive\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\App Paths\\Winword.exe" -ErrorAction SilentlyContinue).'(default)'
-  if ($path -and (Test-Path -LiteralPath $path)) { $path; break }
-}`;
-  return powershell(script, { capture: true }).stdout.trim() || null;
+  for (const hive of ["HKLM", "HKCU"]) {
+    const path = regQuery(`${hive}\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\App Paths\\Winword.exe`, ["/ve"]);
+    if (path && existsSync(path)) return path;
+  }
+  return null;
 }
 
 const windowsOffice = () => join(process.env.ProgramFiles || "C:\\Program Files", "LibreOffice", "program");
 
-function windowsPackages(options) {
-  if (!which("winget")) fail("Install Microsoft's App Installer (WinGet): https://aka.ms/getwinget . Then rerun.");
-  const packages = ["Python.Python.3.12", "Git.Git", "GitHub.cli", "astral-sh.uv"];
-  if (options.hyperframes || options.demo) packages.push("Gyan.FFmpeg");
+// Selects the WinGet packages whose commands are not already usable. Probes are functions so unneeded ones never run.
+export function windowsPackageIds(options, present) {
+  const packages = [["Python.Python.3.12", present.python], ["Git.Git", present.git], ["GitHub.cli", present.gh],
+    ["astral-sh.uv", present.uv]];
+  if (options.hyperframes || options.demo) packages.push(["Gyan.FFmpeg", present.ffmpeg]);
   if (options.demo) {
-    packages.push("oschwartz10612.Poppler");
-    if (!which("code")) packages.push("Microsoft.VisualStudioCode");
-    if (!windowsWordPath() && !which("soffice.com") && !existsSync(join(windowsOffice(), "soffice.com"))) {
-      packages.push("TheDocumentFoundation.LibreOffice");
-    }
+    packages.push(["oschwartz10612.Poppler", present.poppler], ["Microsoft.VisualStudioCode", present.code],
+      ["TheDocumentFoundation.LibreOffice", present.office]);
   }
+  return packages.filter(([, found]) => !found()).map(([id]) => id);
+}
+
+// First word of each listed line: package names from `brew list --versions`.
+export const listedNames = (output) => new Set(output.split(/\r?\n/).map((line) => line.trim().split(/\s+/)[0]).filter(Boolean));
+
+// Packages that `dpkg-query -W -f '${Package} ${db:Status-Status}\n'` reports as installed.
+export const dpkgInstalled = (output) => new Set(output.split(/\r?\n/).map((line) => line.trim().split(/\s+/))
+  .filter(([name, status]) => name && status === "installed").map(([name]) => name));
+
+function windowsPackages(options) {
+  refreshWindowsPath();
+  const packages = windowsPackageIds(options, {
+    python: () => Boolean(findPython()),
+    git: () => which("git"),
+    gh: () => which("gh"),
+    uv: () => which("uv"),
+    ffmpeg: () => which("ffmpeg") && which("ffprobe"),
+    poppler: () => which("pdftoppm"),
+    code: () => which("code"),
+    office: () => windowsWordPath() || which("soffice.com") || existsSync(join(windowsOffice(), "soffice.com")),
+  });
+  if (!packages.length) { console.log("Native packages are already present."); return; }
+  if (!which("winget")) fail("Install Microsoft's App Installer (WinGet): https://aka.ms/getwinget . Then rerun.");
   for (const id of packages) {
     run("winget", ["install", "--id", id, "--exact", "--source", "winget", "--accept-package-agreements",
       "--accept-source-agreements", "--disable-interactivity"], { allow: wingetCurrent });
@@ -60,7 +92,11 @@ function macPackages(options, temporary) {
   const packages = ["python@3.12", "git", "gh", "uv"];
   if (options.hyperframes || options.demo) packages.push("ffmpeg");
   if (options.demo) packages.push("poppler");
-  run(brew, ["install", ...packages]);
+  const listed = listedNames(run(brew, ["list", "--versions", ...packages],
+    { capture: true, silent: true, quiet: true, allow: [0, 1] }).stdout);
+  const missing = packages.filter((name) => !listed.has(name));
+  if (missing.length) run(brew, ["install", ...missing]);
+  else console.log("Homebrew packages are already present.");
   const casks = [];
   if (options.demo) {
     if (!which("code") && !existsSync("/Applications/Visual Studio Code.app")) casks.push("visual-studio-code");
@@ -78,24 +114,31 @@ function linuxPackages(options, temporary) {
   if (parseInt(release.VERSION_ID, 10) < (release.ID === "ubuntu" ? 24 : 12)) fail("Upgrade to Ubuntu 24.04+ or Debian 12+.");
   if (process.arch !== "x64") fail("The default Chrome-based Playwright recipe requires Linux x86_64.");
   if (process.getuid() === 0) fail("Run as your normal user. The installer uses sudo for system packages.");
-  run("sudo", ["apt-get", "update"]);
   const packages = ["ca-certificates", "curl", "git", "gh", "python3", "python3-venv"];
   if (options.hyperframes || options.demo) packages.push("ffmpeg");
   if (options.demo) packages.push("poppler-utils");
   if (options.demo && !which("soffice")) packages.push("libreoffice-writer", "libreoffice-impress");
-  run("sudo", ["apt-get", "install", "-y", ...packages]);
+  const chrome = "google-chrome-stable";
+  const installed = dpkgInstalled(run("dpkg-query", ["-W", "-f", "${Package} ${db:Status-Status}\\n", ...packages, chrome],
+    { capture: true, silent: true, quiet: true, allow: [0, 1] }).stdout);
+  const missing = packages.filter((name) => !installed.has(name));
+  const needCode = options.demo && !which("code");
+  const needChrome = (options.playwright || options.hyperframes) && !installed.has(chrome);
+  if (missing.length || needCode || needChrome) run("sudo", ["apt-get", "update"]);
+  if (missing.length) run("sudo", ["apt-get", "install", "-y", ...missing]);
+  else console.log("APT packages are already present.");
   // curl honors the environment's proxy settings.
   const deb = (url, name) => {
     const path = join(temporary, name);
     run("curl", ["-fsSL", url, "-o", path]);
     run("sudo", ["apt-get", "install", "-y", path]);
   };
-  if (options.demo && !which("code")) deb("https://update.code.visualstudio.com/latest/linux-deb-x64/stable", "code.deb");
-  if (options.playwright || options.hyperframes) {
-    deb("https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb", "chrome.deb");
+  if (needCode) deb("https://update.code.visualstudio.com/latest/linux-deb-x64/stable", "code.deb");
+  if (needChrome) deb("https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb", "chrome.deb");
+  if (!which("uv") && !existsSync(join(homedir(), ".local", "bin", "uv"))) {
+    run("curl", ["-fsSL", "https://astral.sh/uv/install.sh", "-o", join(temporary, "uv.sh")]);
+    run("sh", [join(temporary, "uv.sh")], { env: { ...process.env, UV_NO_MODIFY_PATH: "1" } });
   }
-  run("curl", ["-fsSL", "https://astral.sh/uv/install.sh", "-o", join(temporary, "uv.sh")]);
-  run("sh", [join(temporary, "uv.sh")], { env: { ...process.env, UV_NO_MODIFY_PATH: "1" } });
 }
 
 export function systemPackages(options, temporary) {
@@ -120,8 +163,33 @@ export function uvToolPath() {
   prependPath(capture("uv", ["tool", "dir", "--bin"]));
 }
 
-function npmGlobal(packages) {
-  if (!packages.length) return;
+const splitSpec = (spec) => {
+  const at = spec.lastIndexOf("@");
+  return at > 0 ? [spec.slice(0, at), spec.slice(at + 1)] : [spec, ""];
+};
+
+function installedManifest(root, name) {
+  const manifest = join(root, name, "package.json");
+  if (!existsSync(manifest)) return null;
+  try { return JSON.parse(readFileSync(manifest, "utf8")); } catch { return null; }
+}
+
+// Pinned specs not installed at exactly their pinned version under the global root.
+export function npmMissing(root, specs) {
+  return specs.filter((spec) => {
+    const [name, version] = splitSpec(spec);
+    const actual = installedManifest(root, name);
+    return !actual || actual.name !== name || (version && actual.version !== version);
+  });
+}
+
+let npmRoot;
+const globalRoot = () => (npmRoot ??= capture("npm", ["root", "--global"], { quiet: true }).trim());
+
+function npmGlobal(specs) {
+  if (!specs.length) return;
+  const packages = npmMissing(globalRoot(), specs);
+  if (!packages.length) { console.log("Global npm packages are already at their pinned versions."); return; }
   const prefix = capture("npm", ["prefix", "--global"], { quiet: true });
   const modules = windows ? prefix : join(prefix, "lib");
   let writable = true;
@@ -138,35 +206,76 @@ function npmGlobal(packages) {
 }
 
 export function skillsAdd(runSkills, sources) {
-  for (const source of sources) {
+  for (const source of pendingSkillSources(sources)) {
     runSkills(["add", source, "--global", "--skill", "*", "--yes", "--copy"], { env: { ...process.env, DISABLE_TELEMETRY: "1" } });
   }
 }
 
-function playwrightSmoke(temporary) {
-  run("playwright-cli", ["install-browser", "chrome"]);
-  const session = `-s=promptlings-install-${process.pid}`;
-  try {
-    run("playwright-cli", [session, "open", "about:blank"], { cwd: temporary });
-    const title = capture("playwright-cli",
-      [session, "eval", "() => { document.title = 'promptlings'; return document.title; }", "--raw"], { cwd: temporary });
-    if (title.replace(/^"|"$/g, "") !== "promptlings") fail(`Playwright CLI browser smoke check failed: ${title}`);
-  } finally {
-    try { run("playwright-cli", [session, "close"], { cwd: temporary }); } catch { /* keep the original failure */ }
+export const skillLockPath = (env = process.env) =>
+  env.XDG_STATE_HOME ? join(env.XDG_STATE_HOME, "skills", ".skill-lock.json") : join(homedir(), ".agents", ".skill-lock.json");
+
+const readJson = (path) => { try { return JSON.parse(readFileSync(path, "utf8")); } catch { return null; } };
+
+// A pinned source counts as installed when the lock holds skills from the same repository, commit and path,
+// and each of those skills is still present in the global skills directory.
+export function skillSourceInstalled(lock, source, present) {
+  const match = /^https:\/\/github\.com\/([^/]+\/[^/]+)\/tree\/([^/]+)\/(.+?)\/?$/.exec(source);
+  if (!match) return false;
+  const [, repo, ref, path] = match;
+  const entries = Object.entries(lock?.skills ?? {}).filter(([, entry]) =>
+    entry.sourceType === "github" && entry.ref === ref && `${entry.skillPath ?? ""}`.startsWith(`${path}/`)
+    && (entry.source === repo || entry.sourceUrl === `https://github.com/${repo}.git`));
+  return entries.length > 0 && entries.every(([name]) => present(name));
+}
+
+export function pendingSkillSources(sources, lock = readJson(skillLockPath()),
+  present = (name) => existsSync(join(homedir(), ".agents", "skills", name, "SKILL.md"))) {
+  const pending = sources.filter((source) => !skillSourceInstalled(lock, source, present));
+  for (const source of sources) if (!pending.includes(source)) console.log(`= skills already installed: ${source}`);
+  return pending;
+}
+
+// Folds per-run skill lock entries into the shared lock, keeping each skill's original install time.
+export function mergeSkillLocks(shared, runs) {
+  const merged = shared && typeof shared.version === "number" && shared.skills ? shared : null;
+  const result = merged ?? { version: runs.find(Boolean)?.version ?? 3, skills: {}, dismissed: {} };
+  for (const lock of runs) {
+    for (const [name, entry] of Object.entries(lock?.skills ?? {})) {
+      result.skills[name] = { ...entry, installedAt: result.skills[name]?.installedAt ?? entry.installedAt };
+    }
   }
+  return result;
 }
 
-function hyperframesCheck() {
-  run("ffmpeg", ["-version"]);
-  run("ffprobe", ["-version"]);
-  run("hyperframes", ["browser", "ensure"]);
-  const report = JSON.parse(capture("hyperframes", ["doctor", "--json"]));
-  const failed = ["FFmpeg", "FFprobe", "Chrome"].filter((name) => !report.checks.some((check) => check.name === name && check.ok));
-  if (failed.length) fail(`HyperFrames prerequisites failed: ${failed.join(", ")}`);
-  run("hyperframes", ["--version"]);
+// The skills CLI rewrites one global lock file per skill, so concurrent runs each get a private lock directory
+// and the entries are merged afterwards. Installed skill directories are distinct per skill.
+export async function skillsAddConcurrent(sources, runner = (args, options) => runBuffered(process.execPath, [packageBin("skills"), ...args], options)) {
+  if (!sources.length) return;
+  const states = mkdtempSync(join(tmpdir(), "promptlings-skills-"));
+  try {
+    console.log(`+ skills add (${sources.length} sources in parallel)`);
+    const results = await Promise.all(sources.map((source, index) => {
+      const state = join(states, String(index));
+      mkdirSync(state);
+      return runner(["add", source, "--global", "--skill", "*", "--yes", "--copy"],
+        { env: { ...process.env, DISABLE_TELEMETRY: "1", CI: "true", XDG_STATE_HOME: state } })
+        .then((result) => ({ ...result, source, lock: join(state, "skills", ".skill-lock.json") }));
+    }));
+    for (const { source, output } of results) console.log(`+ skills add ${source}\n${output.trimEnd()}`);
+    const lockPath = skillLockPath();
+    const runs = results.map(({ lock }) => readJson(lock));
+    if (runs.some((lock) => lock && Object.keys(lock.skills ?? {}).length)) {
+      mkdirSync(dirname(lockPath), { recursive: true });
+      writeFileSync(lockPath, JSON.stringify(mergeSkillLocks(readJson(lockPath), runs), null, 2), "utf8");
+    }
+    const failed = results.filter(({ status }) => status !== 0);
+    if (failed.length) fail(`External skill installation failed: ${failed.map(({ source, status }) => `${source} (${status})`).join(", ")}`);
+  } finally {
+    rmSync(states, { recursive: true, force: true });
+  }
 }
 
-function demoCheck() {
+function demoSetup() {
   if (process.platform === "darwin") {
     const code = "/Applications/Visual Studio Code.app/Contents/Resources/app/bin";
     if (!which("code") && existsSync(join(code, "code"))) prependPath(code);
@@ -180,24 +289,16 @@ function demoCheck() {
 [Environment]::SetEnvironmentVariable("Path", ((@($path, '${windowsOffice().replace(/'/g, "''")}') | Where-Object { $_ }) -join ";"), "User")`);
     prependPath(windowsOffice());
   }
-  run("code", ["--version"]);
-  run("code", ["--install-extension", pins.demoTimeExtension]);
-  const office = windows ? "soffice.com" : "soffice";
-  if (which(office)) run(office, ["--version"]);
-  else if (windows && windowsWordPath()) console.log("Document rendering: Microsoft Word.");
-  else if (process.platform === "darwin" && existsSync("/Applications/Microsoft Word.app")) console.log("Document rendering: Microsoft Word.");
-  else fail("Document rendering needs Microsoft Word or LibreOffice.");
-  run("pdftoppm", ["-v"]);
-  run("ffmpeg", ["-version"]);
-  run("diff2html", ["--version"]);
+  const [extension, version] = pins.demoTimeExtension.split("@");
+  if (existsSync(join(homedir(), ".vscode", "extensions", `${extension.toLowerCase()}-${version}`, "package.json"))) {
+    console.log(`= VS Code extension already installed: ${pins.demoTimeExtension}`);
+  } else run("code", ["--install-extension", pins.demoTimeExtension]);
 }
 
 // Confirms each pinned experience package is installed at its exact version under the global root.
 export function verifyExperience(root, packages) {
   for (const spec of packages) {
-    const at = spec.lastIndexOf("@");
-    const name = at > 0 ? spec.slice(0, at) : spec;
-    const version = at > 0 ? spec.slice(at + 1) : "";
+    const [name, version] = splitSpec(spec);
     const manifest = join(root, name, "package.json");
     if (!existsSync(manifest)) fail(`Experience toolkit package missing: ${name}`);
     const actual = JSON.parse(readFileSync(manifest, "utf8"));
@@ -207,14 +308,12 @@ export function verifyExperience(root, packages) {
   }
 }
 
-// System packages, global command-line tools, external skills and their smoke checks.
-export function installTools(options, temporary, runSkills) {
+// System packages, global command-line tools, browsers and external skills.
+export async function installTools(options, temporary) {
   if (options.systemPackages) systemPackages(options, temporary);
   prependPath(join(homedir(), ".local", "bin"));
   for (const command of ["uv", "git", "gh"]) if (!which(command)) fail(`Missing prerequisite: ${command}.`);
   if (!findPython()) fail("Python 3.11+ is required. Install it normally or rerun without --no-system-packages.");
-  run("git", ["--version"]);
-  run("gh", ["--version"]);
   npmGlobal([
     options.playwright && pins.playwright,
     options.hyperframes && pins.hyperframes,
@@ -222,7 +321,7 @@ export function installTools(options, temporary, runSkills) {
     ...(options.experience ? pins.experiencePackages : []),
   ].filter(Boolean));
   if (options.experience) {
-    const root = capture("npm", ["root", "--global"], { quiet: true }).trim();
+    const root = globalRoot();
     verifyExperience(root, pins.experiencePackages);
     console.log(`Experience toolkit: ${root}`);
   }
@@ -236,8 +335,8 @@ export function installTools(options, temporary, runSkills) {
     ] : []),
     ...(options.experience ? [pins.frontendDesignSkill, pins.playwrightSkills, pins.hyperframesSkills] : []),
   ].filter(Boolean));
-  if (skillSources.size) skillsAdd(runSkills, [...skillSources]);
-  if (options.playwright) playwrightSmoke(temporary);
-  if (options.hyperframes) hyperframesCheck();
-  if (options.demo) demoCheck();
+  await skillsAddConcurrent(pendingSkillSources([...skillSources]));
+  if (options.playwright) run("playwright-cli", ["install-browser", "chrome"]);
+  if (options.hyperframes) run("hyperframes", ["browser", "ensure"]);
+  if (options.demo) demoSetup();
 }

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "promptlings",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "promptlings",
-      "version": "0.1.0-alpha.1",
+      "version": "0.1.0-alpha.2",
       "license": "Apache-2.0",
       "dependencies": {
         "add-mcp": "2.6.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "promptlings",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.2",
   "description": "Install the promptlings agents, skills, Basic Memory and supporting toolchain on any OS.",
   "license": "Apache-2.0",
   "repository": {