@ankhorage/devtools 1.8.5 → 1.9.0

package/dist/tools/skills/assets/ankhorage-project-structure/references/utilities.md

@@ -0,0 +1,62 @@
+# Utility Ownership and Unknown-Value Narrowing
+
+Classify a helper before creating or moving it:
+
+```text
+cross-repository, framework-neutral -> @ankhorage/utility/<category>
+cross-domain inside one package      -> src/utils/<functionName>.ts
+one domain only                      -> src/<domain>/utils/<functionName>.ts
+semantic/domain behavior             -> owning domain, not utils
+```
+
+Do not retain local copies while waiting for a Utility release. Follow the Utility PR, merge,
+release, dependency-update sequence defined by `ankhorage-package-structure`.
+
+## Strong cross-repository candidates
+
+Generic object and unknown-value operations commonly belong in focused Utility subpaths:
+
+```text
+@ankhorage/utility/object
+  readOwnProperty
+  setOwnProperty
+  deleteOwnProperty
+  isRecord
+
+@ankhorage/utility/value
+  asString
+  asNumber
+  asRecord
+```
+
+Create public utilities only after confirming repetition and stable semantics across repositories.
+Do not move feature payload parsers, provider response semantics, or domain validation merely
+because they contain small type guards.
+
+## Absence and failure semantics
+
+Use consistent meanings:
+
+- `isRecord(value)` returns a type-guard boolean.
+- `asRecord(value)` returns the narrowed record or `undefined`.
+- `asString(value)` returns the string or `undefined`.
+- `readOwnProperty(target, key)` returns the owned value or `undefined`.
+- `parse<DomainValue>(value)` returns an explicit domain parse result when callers need to
+  distinguish absent, invalid, and valid values.
+
+Reserve `null` for an intentional domain or serialized value. Do not use `null` as the generic
+failure result for type narrowing when `undefined` expresses absence. When failure details matter,
+use a discriminated result instead of alternating between `null` and `undefined`.
+
+## Avoid false utilities
+
+Keep these with their owner:
+
+- `readProjectDeployConfig`
+- `readSecretPayload`
+- `parseStudioModuleState`
+- API response validation with feature-specific error policy
+- helpers that encode manifest, route, auth, deploy, or provider semantics
+
+A utility is not a place to hide complexity or shorten a file. It must represent a reusable,
+cohesive capability with stable behavior.

package/dist/tools/skills/managed.d.ts

@@ -0,0 +1,5 @@
+import type { ManagedFileStatus, ManagedFileSyncResult } from '../shared/managedFiles.js';
+export declare function inspectManagedSkills(targetDirectory: string, devtoolsVersion: string): Promise<readonly ManagedFileStatus[]>;
+export declare function syncManagedSkills(targetDirectory: string, devtoolsVersion: string, options: {
+    readonly dryRun: boolean;
+}): Promise<readonly ManagedFileSyncResult[]>;

package/dist/tools/skills/managed.js

@@ -0,0 +1,224 @@
+import { lstat, mkdir, readdir, readFile, rmdir, unlink, writeFile } from 'node:fs/promises';
+import { dirname, join, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { assertManagedSkillPath, createManifestContents, isNodeError, MANIFEST_PATH, readManagedSkillsManifest, resolveManagedPath, SKILLS_ROOT, } from './manifest.js';
+const CANONICAL_SKILL_NAMES = ['ankhorage-coding-rules', 'ankhorage-project-structure'];
+export async function inspectManagedSkills(targetDirectory, devtoolsVersion) {
+    return (await createManagedSkillPlan(targetDirectory, devtoolsVersion)).statuses;
+}
+export async function syncManagedSkills(targetDirectory, devtoolsVersion, options) {
+    const plan = await createManagedSkillPlan(targetDirectory, devtoolsVersion);
+    const results = [];
+    for (const status of plan.statuses) {
+        const action = getSyncAction(status, options.dryRun);
+        if (!options.dryRun) {
+            await applySkillAction(targetDirectory, status, action, plan);
+        }
+        results.push({ relativePath: status.relativePath, action });
+    }
+    return results;
+}
+async function applySkillAction(targetDirectory, status, action, plan) {
+    if (action === 'unchanged') {
+        return;
+    }
+    const targetPath = resolveManagedPath(targetDirectory, status.relativePath);
+    await assertNoSymlinkSegments(targetDirectory, status.relativePath);
+    if (action === 'removed') {
+        await unlink(targetPath);
+        await removeEmptyParentDirectories(targetDirectory, dirname(targetPath));
+        return;
+    }
+    await mkdir(dirname(targetPath), { recursive: true });
+    const contents = status.relativePath === MANIFEST_PATH
+        ? plan.manifestContents
+        : plan.contentsByPath.get(status.relativePath);
+    if (contents === undefined) {
+        throw new Error(`Missing canonical skill contents for ${status.relativePath}.`);
+    }
+    await writeFile(targetPath, contents);
+}
+async function assertNoSymlinkSegments(targetDirectory, relativePath) {
+    let currentPath = targetDirectory;
+    for (const segment of relativePath.split('/')) {
+        currentPath = join(currentPath, segment);
+        try {
+            const stats = await lstat(currentPath);
+            if (stats.isSymbolicLink()) {
+                throw new Error(`Managed skill path must not contain symbolic links: ${relativePath}`);
+            }
+        }
+        catch (error) {
+            if (isNodeError(error) && error.code === 'ENOENT') {
+                return;
+            }
+            throw error;
+        }
+    }
+}
+async function collectCanonicalSkillFiles() {
+    const contentsByPath = new Map();
+    for (const skillName of CANONICAL_SKILL_NAMES) {
+        const sourceDirectory = fileURLToPath(new URL(`./assets/${skillName}/`, import.meta.url));
+        const files = await readDirectoryFiles(sourceDirectory);
+        assertSkillName(skillName, files);
+        for (const [skillRelativePath, contents] of files) {
+            contentsByPath.set(`${SKILLS_ROOT}/${skillName}/${skillRelativePath}`, contents);
+        }
+    }
+    return contentsByPath;
+}
+async function collectObsoletePaths(targetDirectory, desiredPaths, previousManifest) {
+    const obsoletePaths = new Set();
+    for (const skillName of CANONICAL_SKILL_NAMES) {
+        const skillRoot = `${SKILLS_ROOT}/${skillName}`;
+        for (const existingPath of await readTargetDirectoryFiles(targetDirectory, skillRoot)) {
+            if (!desiredPaths.has(existingPath)) {
+                obsoletePaths.add(existingPath);
+            }
+        }
+    }
+    if (previousManifest !== null) {
+        for (const [skillName, entry] of Object.entries(previousManifest.skills)) {
+            if (CANONICAL_SKILL_NAMES.includes(skillName)) {
+                continue;
+            }
+            for (const managedPath of Object.keys(entry.files)) {
+                if (await isRegularManagedFile(targetDirectory, managedPath)) {
+                    obsoletePaths.add(managedPath);
+                }
+            }
+        }
+    }
+    return [...obsoletePaths].sort();
+}
+async function createManagedSkillPlan(targetDirectory, devtoolsVersion) {
+    const previousManifest = await readManagedSkillsManifest(targetDirectory);
+    const contentsByPath = await collectCanonicalSkillFiles();
+    const desiredPaths = new Set(contentsByPath.keys());
+    const manifestContents = createManifestContents(contentsByPath, devtoolsVersion, CANONICAL_SKILL_NAMES);
+    const statuses = [];
+    for (const [relativePath, contents] of [...contentsByPath.entries()].sort()) {
+        statuses.push(await inspectDesiredFile(targetDirectory, relativePath, contents));
+    }
+    for (const relativePath of await collectObsoletePaths(targetDirectory, desiredPaths, previousManifest)) {
+        statuses.push({ relativePath, state: 'obsolete' });
+    }
+    statuses.push(await inspectDesiredFile(targetDirectory, MANIFEST_PATH, Buffer.from(manifestContents)));
+    return { contentsByPath, manifestContents, statuses };
+}
+function getSyncAction(status, dryRun) {
+    if (status.state === 'current') {
+        return 'unchanged';
+    }
+    if (status.state === 'obsolete') {
+        return dryRun ? 'would-remove' : 'removed';
+    }
+    if (status.state === 'missing') {
+        return dryRun ? 'would-create' : 'created';
+    }
+    return dryRun ? 'would-update' : 'updated';
+}
+async function inspectDesiredFile(targetDirectory, relativePath, canonicalContents) {
+    await assertNoSymlinkSegments(targetDirectory, relativePath);
+    try {
+        const targetContents = await readFile(resolveManagedPath(targetDirectory, relativePath));
+        return {
+            relativePath,
+            state: Buffer.compare(targetContents, canonicalContents) === 0 ? 'current' : 'outdated',
+        };
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === 'ENOENT') {
+            return { relativePath, state: 'missing' };
+        }
+        throw error;
+    }
+}
+async function isRegularManagedFile(targetDirectory, relativePath) {
+    assertManagedSkillPath(relativePath);
+    await assertNoSymlinkSegments(targetDirectory, relativePath);
+    try {
+        return (await lstat(resolveManagedPath(targetDirectory, relativePath))).isFile();
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === 'ENOENT') {
+            return false;
+        }
+        throw error;
+    }
+}
+async function readDirectoryFiles(directory, prefix = '') {
+    const files = new Map();
+    const entries = (await readdir(directory, { withFileTypes: true })).sort((left, right) => left.name.localeCompare(right.name));
+    for (const entry of entries) {
+        const entryPath = join(directory, entry.name);
+        const relativePath = prefix === '' ? entry.name : `${prefix}/${entry.name}`;
+        if (entry.isDirectory()) {
+            for (const nestedFile of await readDirectoryFiles(entryPath, relativePath)) {
+                files.set(...nestedFile);
+            }
+        }
+        else if (entry.isFile()) {
+            files.set(relativePath, await readFile(entryPath));
+        }
+        else {
+            throw new Error(`Canonical skill assets must contain only files and directories: ${entryPath}`);
+        }
+    }
+    return files;
+}
+async function readTargetDirectoryFiles(targetDirectory, relativeDirectory) {
+    await assertNoSymlinkSegments(targetDirectory, relativeDirectory);
+    const directory = resolveManagedPath(targetDirectory, relativeDirectory);
+    let entries;
+    try {
+        entries = await readdir(directory, { withFileTypes: true });
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === 'ENOENT') {
+            return [];
+        }
+        throw error;
+    }
+    const files = [];
+    for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+        const relativePath = `${relativeDirectory}/${entry.name}`;
+        if (entry.isDirectory()) {
+            files.push(...(await readTargetDirectoryFiles(targetDirectory, relativePath)));
+        }
+        else if (entry.isFile()) {
+            files.push(relativePath);
+        }
+        else {
+            throw new Error(`Managed skill trees must not contain symbolic links: ${relativePath}`);
+        }
+    }
+    return files;
+}
+async function removeEmptyParentDirectories(targetDirectory, initialDirectory) {
+    const stopDirectory = resolveManagedPath(targetDirectory, SKILLS_ROOT);
+    let directory = initialDirectory;
+    while (directory.startsWith(`${stopDirectory}${sep}`)) {
+        try {
+            await rmdir(directory);
+        }
+        catch (error) {
+            if (isNodeError(error) && ['ENOENT', 'ENOTEMPTY'].includes(error.code ?? '')) {
+                return;
+            }
+            throw error;
+        }
+        directory = dirname(directory);
+    }
+}
+function assertSkillName(expectedName, files) {
+    const skillFile = files.get('SKILL.md');
+    if (skillFile === undefined) {
+        throw new Error(`Canonical skill is missing SKILL.md: ${expectedName}`);
+    }
+    const match = /^---\n[\s\S]*?^name:\s*(.+)$/mu.exec(Buffer.from(skillFile).toString('utf8'));
+    if (match?.[1]?.trim() !== expectedName) {
+        throw new Error(`Canonical skill directory and frontmatter names differ: ${expectedName}`);
+    }
+}

package/dist/tools/skills/manifest.d.ts

@@ -0,0 +1,16 @@
+export declare const MANIFEST_PATH = ".agents/.devtools-manifest.json";
+export declare const SKILLS_ROOT = ".agents/skills";
+interface ManagedSkillManifestEntry {
+    readonly files: Readonly<Record<string, string>>;
+}
+export interface ManagedSkillsManifest {
+    readonly schemaVersion: 1;
+    readonly sourceDevtoolsVersion: string;
+    readonly skills: Readonly<Record<string, ManagedSkillManifestEntry>>;
+}
+export declare function createManifestContents(contentsByPath: ReadonlyMap<string, Uint8Array>, devtoolsVersion: string, skillNames: readonly string[]): string;
+export declare function readManagedSkillsManifest(targetDirectory: string): Promise<ManagedSkillsManifest | null>;
+export declare function assertManagedSkillPath(relativePath: string): void;
+export declare function resolveManagedPath(targetDirectory: string, relativePath: string): string;
+export declare function isNodeError(error: unknown): error is NodeJS.ErrnoException;
+export {};

package/dist/tools/skills/manifest.js

@@ -0,0 +1,95 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { posix, relative, resolve } from 'node:path';
+export const MANIFEST_PATH = '.agents/.devtools-manifest.json';
+export const SKILLS_ROOT = '.agents/skills';
+const MANIFEST_SCHEMA_VERSION = 1;
+export function createManifestContents(contentsByPath, devtoolsVersion, skillNames) {
+    const skills = Object.fromEntries(skillNames.map((skillName) => {
+        const prefix = `${SKILLS_ROOT}/${skillName}/`;
+        const files = Object.fromEntries([...contentsByPath.entries()]
+            .filter(([relativePath]) => relativePath.startsWith(prefix))
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([relativePath, contents]) => [relativePath, sha256(contents)]));
+        return [skillName, { files }];
+    }));
+    const manifest = {
+        schemaVersion: MANIFEST_SCHEMA_VERSION,
+        sourceDevtoolsVersion: devtoolsVersion,
+        skills,
+    };
+    return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+export async function readManagedSkillsManifest(targetDirectory) {
+    try {
+        const contents = await readFile(resolveManagedPath(targetDirectory, MANIFEST_PATH), 'utf8');
+        return parseManagedSkillsManifest(JSON.parse(contents));
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === 'ENOENT') {
+            return null;
+        }
+        throw error;
+    }
+}
+export function assertManagedSkillPath(relativePath) {
+    assertSafeRelativePath(relativePath);
+    if (!relativePath.startsWith(`${SKILLS_ROOT}/`)) {
+        throw new Error(`Managed skill manifest path is outside ${SKILLS_ROOT}: ${relativePath}`);
+    }
+}
+export function resolveManagedPath(targetDirectory, relativePath) {
+    assertSafeRelativePath(relativePath);
+    const targetPath = resolve(targetDirectory, ...relativePath.split('/'));
+    const relativeTarget = relative(resolve(targetDirectory), targetPath);
+    if (relativeTarget.startsWith('..') || relativeTarget === '') {
+        throw new Error(`Managed path escapes the target repository: ${relativePath}`);
+    }
+    return targetPath;
+}
+export function isNodeError(error) {
+    return error instanceof Error && 'code' in error;
+}
+function parseManagedSkillsManifest(value) {
+    if (!isRecord(value) || value.schemaVersion !== MANIFEST_SCHEMA_VERSION) {
+        throw new Error(`Unsupported managed skills manifest at ${MANIFEST_PATH}.`);
+    }
+    if (typeof value.sourceDevtoolsVersion !== 'string' || !isRecord(value.skills)) {
+        throw new Error(`Invalid managed skills manifest at ${MANIFEST_PATH}.`);
+    }
+    const skillEntries = Object.entries(value.skills).map(([skillName, rawEntry]) => {
+        if (!isSafeName(skillName) || !isRecord(rawEntry) || !isRecord(rawEntry.files)) {
+            throw new Error(`Invalid managed skill entry in ${MANIFEST_PATH}: ${skillName}`);
+        }
+        const files = Object.fromEntries(Object.entries(rawEntry.files).map(([relativePath, hash]) => {
+            assertManagedSkillPath(relativePath);
+            if (typeof hash !== 'string' || !/^sha256:[a-f0-9]{64}$/u.test(hash)) {
+                throw new Error(`Invalid managed skill hash in ${MANIFEST_PATH}: ${relativePath}`);
+            }
+            return [relativePath, hash];
+        }));
+        return [skillName, { files }];
+    });
+    return {
+        schemaVersion: MANIFEST_SCHEMA_VERSION,
+        sourceDevtoolsVersion: value.sourceDevtoolsVersion,
+        skills: Object.fromEntries(skillEntries),
+    };
+}
+function assertSafeRelativePath(relativePath) {
+    if (relativePath === '' ||
+        relativePath !== posix.normalize(relativePath) ||
+        relativePath.startsWith('/') ||
+        relativePath.split('/').some((segment) => segment === '..' || segment === '')) {
+        throw new Error(`Unsafe managed path: ${relativePath}`);
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isSafeName(value) {
+    return /^[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(value);
+}
+function sha256(contents) {
+    return `sha256:${createHash('sha256').update(contents).digest('hex')}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/devtools",
-  "version": "1.8.5",
+  "version": "1.9.0",
   "description": "Shared development tools and repository standards for Ankhorage",
   "license": "MIT",
   "homepage": "https://github.com/ankhorage/devtools#readme",
@@ -25,6 +25,10 @@
       "devtools.knip",
       "devtools.sync",
       "devtools.status",
+      "devtools.agents.sync",
+      "devtools.agents.status",
+      "devtools.skills.sync",
+      "devtools.skills.status",
       "devtools.eslint.sync",
       "devtools.eslint.status",
       "devtools.prettier.sync",
@@ -85,7 +89,7 @@
     "examples"
   ],
   "scripts": {
-    "build": "rm -rf dist tsconfig.tsbuildinfo && tsc && mkdir -p dist/tools/prettier dist/tools/workflows dist/tools/vscode && cp src/tools/prettier/index.cjs dist/tools/prettier/index.cjs && cp -R src/tools/workflows/files dist/tools/workflows/files && cp -R src/tools/vscode/files dist/tools/vscode/files",
+    "build": "rm -rf dist tsconfig.tsbuildinfo && tsc && mkdir -p dist/tools/prettier dist/tools/workflows dist/tools/vscode dist/tools/skills && cp src/tools/prettier/index.cjs dist/tools/prettier/index.cjs && cp -R src/tools/workflows/files dist/tools/workflows/files && cp -R src/tools/vscode/files dist/tools/vscode/files && cp -R src/tools/skills/assets dist/tools/skills/assets",
     "typecheck": "bun x tsc --noEmit -p tsconfig.test.json",
     "doctor": "ankhorage-doctor validate .",
     "knip:check": "knip",
@@ -102,7 +106,7 @@
   },
   "dependencies": {
     "@ankhorage/utility": "^0.2.0",
-    "@changesets/cli": "^2.31.1",
+    "@changesets/cli": "^3.0.1",
     "@eslint/compat": "^2.1.0",
     "@eslint/js": "^10.0.1",
     "eslint": "^10.9.1",
@@ -113,7 +117,7 @@
     "eslint-plugin-react-hooks": "^7.1.1",
     "eslint-plugin-react-native": "^5.0.0",
     "eslint-plugin-security": "^4.0.1",
-    "eslint-plugin-simple-import-sort": "^12.1.1",
+    "eslint-plugin-simple-import-sort": "^14.0.0",
     "eslint-plugin-unused-imports": "^4.4.1",
     "knip": "^6.33.0",
     "prettier": "^3.9.6",
@@ -123,8 +127,8 @@
     "@ankhorage/ankh": "^0.8.4",
     "@ankhorage/doctor": "0.10.4",
     "@types/bun": "^1.4.0",
-    "@types/node": "^25.9.5",
-    "typescript": "^5.9.3"
+    "@types/node": "^26.4.0",
+    "typescript": "~6.0.3"
   },
   "packageManager": "bun@1.4.0"
 }