@duplojs/agents-kit 0.0.0-stage → 0.1.0-beta.10

package/README.md

@@ -1,3 +1,82 @@
-# Temporary Holding Version
+# @duplojs/agents-kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Skills and conceptual documentation for agents working with the DuploJS ecosystem.
+
+Documentation sources, TypeScript examples, and fixtures are stored in [`docs/concepts`](docs/concepts) and [`docs/API`](docs/API). The build generates `docs/concepts.llms.md`, a documentation summary for core concepts, the server, clients, testing, and Type-Driven Design, an `index.llms.md` summary in each API domain directory, and [`docs/API.llms.md`](docs/API.llms.md), a compact table of contents linking to those API summaries. The summaries and their documentation are included in the published package.
+
+From a consuming project, locate the installed concepts summary with:
+
+```sh
+node --input-type=module -e 'import { fileURLToPath } from "node:url"; console.log(fileURLToPath(import.meta.resolve("@duplojs/agents-kit/docs/concepts.llms.md")))'
+```
+
+Read the relevant pages by resolving their links relative to the summary. Before the first monorepo build, consult each domain's `index.md` in `docs/concepts`.
+
+Use each API domain's `index.llms.md` to find a public function by its exported namespace and name, such as `DArray.map` in [`docs/API/10-lang/10-array/index.llms.md`](docs/API/10-lang/10-array/index.llms.md). The other current domains are [Chrono](docs/API/10-lang/10-chrono/index.llms.md), [Common](docs/API/10-lang/10-common/index.llms.md), [DataStructure](docs/API/10-lang/10-dataStructure/index.llms.md), [Either](docs/API/10-lang/10-either/index.llms.md), and [Generator](docs/API/10-lang/10-generator/index.llms.md). API sources are primarily TypeScript files combining descriptions and typed usage examples. Each summary exposes their headers and links to those files.
+
+The `skills install` command creates symbolic links to the package's skills by default.
+The boolean `--copy` option copies the skills instead.
+Each installation removes the skill's destination and replaces it with the requested copy or link. The target of any existing symbolic link is preserved.
+
+```sh
+pnpm exec duplojs-agents-kit skills install
+pnpm exec duplojs-agents-kit skills install http-server --type codex
+pnpm exec duplojs-agents-kit skills install http-client --copy
+pnpm exec duplojs-agents-kit skills install command --type codex
+pnpm exec duplojs-agents-kit skills install server --type codex
+pnpm exec duplojs-agents-kit skills install modeling --type codex
+pnpm exec duplojs-agents-kit skills install test --type codex
+```
+
+Run `skills update` to update DuploJS skills already installed in the selected agent folder. Symbolic links are recreated, including broken links, and copied directories are replaced with a fresh copy, removing obsolete files. Each skill keeps its installation mode. It only updates skills still available in the installed package. Unrelated entries and skills no longer available in the package are preserved; missing skills are not installed.
+
+```sh
+pnpm exec duplojs-agents-kit skills update
+pnpm exec duplojs-agents-kit skills update --type codex
+pnpm exec duplojs-agents-kit skills update --type claude
+```
+
+Two independently installable skills cover HTTP:
+
+- `http-server` (`duplojs-http-server`) guides server setup, routes, and reusable flows.
+- `http-client` (`duplojs-http-client`) guides typed calls to DuploJS or external APIs, response expectations, hooks, Predicted mode, SSE, and streams.
+
+The `server` skill (`duplojs-server`) guides filesystem operations, typed I/O errors, file and folder structures, environment configuration, and process capabilities through `@duplojs/server`. It prioritizes the package's runtime abstractions and distinguishes the process working directory from the module directory.
+
+The `modeling` skill (`duplojs-modeling`) guides business system modeling and implementation with Type-Driven Design: understanding the existing domain, entity lifecycles, flags, facts, evidence, aggregates, repositories, use cases, and infrastructure boundaries. It starts with architecture boundaries and the affected domain contracts, then selects conceptual reading according to the responsibility being changed, including for application or infrastructure work.
+
+The `test` skill (`duplojs-test`) guides testing DuploJS results and type contracts, selecting expected Either information, monitoring new result variants with exhaustive selectors, and isolating server dependencies through `TESTImplementation`. It also points to the concepts for organizing E2E tests with `@duplojs/playwright`.
+
+The `command` skill guides the creation of typed CLI commands with `@duplojs/server/command`, including arguments, options, subcommands, help, and executable entry points. Running `skills install` without a skill installs all supported skills. References and checked TypeScript examples are included in both copied and linked installations.
+
+The `setup` command creates `AGENTS.md` by default, or `CLAUDE.md` with `--type claude`, in the current project if needed and synchronizes a marked coding conventions block while preserving the surrounding content:
+
+```sh
+pnpm exec duplojs-agents-kit setup
+pnpm exec duplojs-agents-kit setup --type default
+pnpm exec duplojs-agents-kit setup --type claude
+```
+
+The block comes from `instructions/coding-conventions.md`, included in the published package. Every `{{packagePath}}` placeholder is replaced with the path to the installed AgentKit package relative to the directory containing the selected instructions file (the current working directory). Running `setup` again replaces the block between `<!-- duplojs-agents-kit:coding-conventions:start -->` and `<!-- duplojs-agents-kit:coding-conventions:stop -->`. Incomplete or duplicate markers cause an error before writing. The supported setup types are `default` and `claude`.
+
+For AgentKit development, `pnpm run llms` runs the local LLM documentation tools through `bin/index.ts`. The `generate-summary` subcommand generates a documentation summary from a source directory. It preserves introductory content and links to detailed pages and examples according to their exposure level. This local CLI is not included in the published package. From the package root:
+
+```sh
+pnpm run llms generate-summary --input docs/concepts --output docs/concepts.llms.md
+pnpm run llms generate-summary --input docs/API/10-lang/10-array --output docs/API/10-lang/10-array/index.llms.md --ignore '*.llms.md'
+```
+
+The required `--input` option selects the source directory, and `--output` selects an output path ending in `.llms.md`. The optional `--ignore` pattern excludes matching paths; quote patterns such as `'*.llms.md'` to pass them to the command without shell expansion.
+
+The `generate-table-of-content` subcommand uses the same options to collect existing `llms.md` and `*.llms.md` files recursively, including directories without numeric prefixes:
+
+```sh
+pnpm run llms generate-table-of-content --input docs/API --output docs/API.llms.md
+pnpm run llms generate-table-of-content --input docs/API --output docs/API.llms.md --ignore '**/10-chrono/**'
+```
+
+For each directory containing an `index.md`, it includes that index's introduction. When an LLM summary is present in the same directory, it turns the index's Markdown headings into links to that summary, relative to the output file. Each index is paired only with the first summary encountered; additional summaries in the same directory do not duplicate the index. Content after a `---` separator is omitted. Indexes without a summary keep their unlinked headings. Child content is included even when a parent directory has no index; summaries without an index provide no local presentation. Entries retain the directory traversal order, ignored directories are not traversed, and the output itself is excluded. This lets an agent choose a domain before loading its function summary.
+
+In the monorepo, `pnpm --filter @duplojs/agents-kit build` builds the package, then runs `llms generate-summary` for the concepts and each configured API domain, followed by `llms generate-table-of-content` for `docs/API.llms.md`. `pnpm --filter @duplojs/agents-kit test:types` also checks examples and fixtures under `docs/` and `skills/` through `tsconfig.doc.json`, and `pnpm --filter @duplojs/agents-kit test:lint` includes them in the package's lint checks. Skill references link directly to their TypeScript examples under `references/examples/`; these files are included when the skill is copied or linked during installation.
+
+This package follows the configuration of server-oriented DuploJS packages and can run on Node.js, Bun, and Deno.

package/dist/bin/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/index.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { skillsCommand } from "./skills/index.mjs";
+import { setupCommand } from "./setup/index.mjs";
+import * as DSCommand from "@duplojs/server/command";
+//#region scripts/bin/index.ts
+await DSCommand.exec({ subjects: [skillsCommand, setupCommand] }, () => {});
+//#endregion

package/dist/bin/packagePath.d.ts

@@ -0,0 +1,2 @@
+import * as DPath from "@duplojs/lang/path";
+export declare function getPackagePath(): string & DPath.Absolute & DPath.Path;

package/dist/bin/packagePath.mjs

@@ -0,0 +1,12 @@
+import * as DCommon from "@duplojs/lang/common";
+import * as DPath from "@duplojs/lang/path";
+import * as DEither from "@duplojs/lang/either";
+import { findPackageJSON } from "node:module";
+//#region scripts/bin/packagePath.ts
+function getPackagePath() {
+	return DCommon.pipe(DEither.rightPipe(findPackageJSON(".", import.meta.url), DEither.toMaybe, DPath.create, DPath.getParentFolderPath, DEither.toMaybe, DPath.createAbsolute), DEither.whenIsLeft((cause) => {
+		throw new Error("@duplojs/agents-kit path was not found.", { cause });
+	}), DEither.unwrapRight);
+}
+//#endregion
+export { getPackagePath };

package/dist/bin/setup/index.d.ts

@@ -0,0 +1,12 @@
+import * as DCommon from "@duplojs/lang/common";
+import * as DSCommand from "@duplojs/server/command";
+export * from './instructions';
+export declare const SetupTypeEnum: {
+    default: "default";
+    claude: "claude";
+    toTuple: () => readonly ["default", "claude"];
+    has: <GenericValue extends string>(value: GenericValue) => value is GenericValue & ("default" | "claude");
+    contract: <GenericContractValue extends string = "default" | "claude">(...args: (Exclude<"default", GenericContractValue> | Exclude<"claude", GenericContractValue> extends infer InferredMissingValue extends string ? DCommon.IsNever<InferredMissingValue> extends true ? unknown : DCommon.ComputedTypeError<`Enum contract is missing value "${InferredMissingValue}".`> : never) & (Exclude<GenericContractValue, "default" | "claude"> extends infer InferredUnknownValue extends string ? DCommon.IsNever<InferredUnknownValue> extends true ? unknown : DCommon.ComputedTypeError<`Enum contract contains unknown value "${InferredUnknownValue}".`> : never) extends infer InferredRequirement ? DCommon.IsEqual<InferredRequirement, unknown> extends true ? [] : [] & InferredRequirement : never) => /*elided*/ any;
+};
+export type SetupTypeEnum = DCommon.GetEnumValue<typeof SetupTypeEnum>;
+export declare const setupCommand: DSCommand.Command<"setup">;

package/dist/bin/setup/index.mjs

@@ -0,0 +1,33 @@
+import { getPackagePath } from "../packagePath.mjs";
+import { InvalidInstructionsMarkersError, synchronizeInstructions } from "./instructions.mjs";
+import * as DSCommand from "@duplojs/server/command";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import * as DCommon from "@duplojs/lang/common";
+import * as DPath from "@duplojs/lang/path";
+import * as DSCommon from "@duplojs/server/common";
+import * as DSFile from "@duplojs/server/file";
+import * as DEither from "@duplojs/lang/either";
+import * as DPattern from "@duplojs/lang/pattern";
+//#region scripts/bin/setup/index.ts
+const SetupTypeEnum = DCommon.createEnum(["default", "claude"]);
+const setupFileMapper = {
+	default: DPath.declarePath("AGENTS.md"),
+	claude: DPath.declarePath("CLAUDE.md")
+};
+const setupCommand = DSCommand.create("setup", {
+	description: "Synchronize DuploJS coding conventions in the project's AGENTS.md or CLAUDE.md",
+	options: [DSCommand.createOption("type", DDataStructure.literal(SetupTypeEnum.toTuple()))]
+}, async ({ options }) => {
+	const setupType = options.type ?? "default";
+	const packagePath = getPackagePath();
+	const instructionsPath = DPath.resolveRelative([packagePath, DPath.declarePath("instructions/coding-conventions.md")]);
+	await DCommon.asyncPipe(DEither.rightAsyncPipe(DSCommon.getCurrentWorkDirectory(), (directory) => ({
+		targetPath: DPath.resolveRelative([directory, setupFileMapper[setupType]]),
+		relativePackagePath: DPath.computeRelative(directory, packagePath)
+	}), ({ targetPath, relativePackagePath }) => DEither.rightAsyncPipe(DSFile.readTextFile(instructionsPath), (instructions) => DEither.rightAsyncPipe(DCommon.asyncPipe(DSFile.readTextFile(targetPath), DEither.whenIsLeft(DPattern.matchWithErrorOtherwise({ "file-system-read-text-file-not-found": () => DEither.success("") }, (error) => DEither.left("file-system-read-text-file-error", error)))), (content) => synchronizeInstructions(content, instructions, relativePackagePath), (content) => DSFile.writeTextFile(targetPath, content)))), DEither.whenIsLeft((cause) => {
+		console.error(cause);
+		DSCommon.exitProcess(1);
+	}));
+});
+//#endregion
+export { InvalidInstructionsMarkersError, SetupTypeEnum, setupCommand, synchronizeInstructions };

package/dist/bin/setup/instructions.d.ts

@@ -0,0 +1,8 @@
+import * as DCommon from "@duplojs/lang/common";
+import * as DEither from "@duplojs/lang/either";
+import type * as DPath from "@duplojs/lang/path";
+declare const InvalidInstructionsMarkersError_base: abstract new (error: string) => DCommon.DuploJSError<"agents-kit-invalid-instructions-markers", string> & import('@duplojs/lang/kind').Kind<import('@duplojs/lang/kind').Handler<import('@duplojs/lang/kind').Definition<"@DuplojsLangCommon/duplojs-error-agents-kit-invalid-instructions-markers", unknown>>, unknown>;
+export declare class InvalidInstructionsMarkersError extends InvalidInstructionsMarkersError_base {
+}
+export declare function synchronizeInstructions(content: string, instructions: string, packagePath: DPath.AnyPath): DEither.Left<"agents-kit-invalid-instructions-markers", InvalidInstructionsMarkersError> | DEither.Success<string>;
+export {};

package/dist/bin/setup/instructions.mjs

@@ -0,0 +1,27 @@
+import * as DCommon from "@duplojs/lang/common";
+import * as DEither from "@duplojs/lang/either";
+import * as DString from "@duplojs/lang/string";
+//#region scripts/bin/setup/instructions.ts
+const startMarker = "<!-- duplojs-agents-kit:coding-conventions:start -->";
+const stopMarker = "<!-- duplojs-agents-kit:coding-conventions:stop -->";
+var InvalidInstructionsMarkersError = class extends DCommon.DuploJSError.parentClass("agents-kit-invalid-instructions-markers") {};
+function synchronizeInstructions(content, instructions, packagePath) {
+	const resolvedInstructions = DString.replaceAll(instructions, "{{packagePath}}", () => packagePath);
+	const block = `${startMarker}\n${resolvedInstructions}\n${stopMarker}`;
+	const start = DString.indexOf(content, startMarker);
+	const stop = DString.indexOf(content, stopMarker);
+	if (start === void 0 && stop === void 0) {
+		const separator = DCommon.justExec(() => {
+			if (content === "" || DString.endsWith(content, "\n\n")) return "";
+			else if (DString.endsWith(content, "\n")) return "\n";
+			return "\n\n";
+		});
+		return DEither.success(`${content}${separator}${block}\n`);
+	}
+	if (start === void 0 || stop === void 0 || stop < start || DString.indexOf(content, startMarker, start + DString.length(startMarker)) !== void 0 || DString.indexOf(content, stopMarker, stop + DString.length(stopMarker)) !== void 0) return DEither.left("agents-kit-invalid-instructions-markers", new InvalidInstructionsMarkersError("The AgentKit coding conventions block has invalid markers."));
+	const before = DString.slice(content, 0, start);
+	const after = DString.slice(content, stop + DString.length(stopMarker), DString.length(content));
+	return DEither.success(`${before}${block}${after}`);
+}
+//#endregion
+export { InvalidInstructionsMarkersError, synchronizeInstructions };

package/dist/bin/skills/index.d.ts

@@ -0,0 +1,5 @@
+import * as DSCommand from "@duplojs/server/command";
+export * from './install';
+export * from './update';
+export * from './skill';
+export declare const skillsCommand: DSCommand.Command<"skills">;

package/dist/bin/skills/index.mjs

@@ -0,0 +1,11 @@
+import { AgentTypeEnum, SkillEnum, copySkill, getSkillPaths, getSkillsFolder, symlinkSkill } from "./skill.mjs";
+import { installSkillCommand } from "./install.mjs";
+import { updateSkillsCommand } from "./update.mjs";
+import * as DSCommand from "@duplojs/server/command";
+//#region scripts/bin/skills/index.ts
+const skillsCommand = DSCommand.create("skills", {
+	description: "Install or update DuploJS skills",
+	subjects: [installSkillCommand, updateSkillsCommand]
+}, () => {});
+//#endregion
+export { AgentTypeEnum, SkillEnum, copySkill, getSkillPaths, getSkillsFolder, installSkillCommand, skillsCommand, symlinkSkill, updateSkillsCommand };

package/dist/bin/skills/install.d.ts

@@ -0,0 +1,2 @@
+import * as DSCommand from "@duplojs/server/command";
+export declare const installSkillCommand: DSCommand.Command<"install">;

package/dist/bin/skills/install.mjs

@@ -0,0 +1,25 @@
+import { getPackagePath } from "../packagePath.mjs";
+import { AgentTypeEnum, SkillEnum, copySkill, symlinkSkill } from "./skill.mjs";
+import * as DSCommand from "@duplojs/server/command";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import * as DCommon from "@duplojs/lang/common";
+import * as DPath from "@duplojs/lang/path";
+import * as DSFile from "@duplojs/server/file";
+import * as DEither from "@duplojs/lang/either";
+import * as DArray from "@duplojs/lang/array";
+//#region scripts/bin/skills/install.ts
+const installSkillCommand = DSCommand.create("install", {
+	options: [DSCommand.createBooleanOption("copy", { description: "Copy skills instead of creating symbolic links" }), DSCommand.createOption("type", DDataStructure.literal(AgentTypeEnum.toTuple()))],
+	subjects: [DSCommand.createArgument("skill", DDataStructure.literal(SkillEnum.toTuple()), { optional: true })]
+}, async ({ args, options }) => {
+	const agentType = options.type ?? "default";
+	const installSkill = options.copy ? copySkill : symlinkSkill;
+	if (args.skill) {
+		await installSkill(agentType, args.skill);
+		return;
+	}
+	const skillsPath = DPath.resolveRelative([getPackagePath(), DPath.declarePath("skills")]);
+	await DEither.rightAsyncPipe(DSFile.readDirectory(skillsPath), DArray.filter(SkillEnum.has), DArray.map((value) => installSkill(agentType, value)), DCommon.promiseAll);
+});
+//#endregion
+export { installSkillCommand };

package/dist/bin/skills/skill.d.ts

@@ -0,0 +1,35 @@
+import * as DCommon from "@duplojs/lang/common";
+import * as DPath from "@duplojs/lang/path";
+import * as DSFile from "@duplojs/server/file";
+import * as DEither from "@duplojs/lang/either";
+export declare const AgentTypeEnum: {
+    default: "default";
+    claude: "claude";
+    codex: "codex";
+    toTuple: () => readonly ["default", "claude", "codex"];
+    has: <GenericValue extends string>(value: GenericValue) => value is GenericValue & ("default" | "claude" | "codex");
+    contract: <GenericContractValue extends string = "default" | "claude" | "codex">(...args: (Exclude<"default", GenericContractValue> | Exclude<"claude", GenericContractValue> | Exclude<"codex", GenericContractValue> extends infer InferredMissingValue extends string ? DCommon.IsNever<InferredMissingValue> extends true ? unknown : DCommon.ComputedTypeError<`Enum contract is missing value "${InferredMissingValue}".`> : never) & (Exclude<GenericContractValue, "default" | "claude" | "codex"> extends infer InferredUnknownValue extends string ? DCommon.IsNever<InferredUnknownValue> extends true ? unknown : DCommon.ComputedTypeError<`Enum contract contains unknown value "${InferredUnknownValue}".`> : never) extends infer InferredRequirement ? DCommon.IsEqual<InferredRequirement, unknown> extends true ? [] : [] & InferredRequirement : never) => /*elided*/ any;
+};
+type AgentTypeEnum = DCommon.GetEnumValue<typeof AgentTypeEnum>;
+export declare const SkillEnum: {
+    fundamental: "fundamental";
+    "http-server": "http-server";
+    "http-client": "http-client";
+    command: "command";
+    server: "server";
+    modeling: "modeling";
+    test: "test";
+    toTuple: () => readonly ["fundamental", "http-server", "http-client", "command", "server", "modeling", "test"];
+    has: <GenericValue extends string>(value: GenericValue) => value is GenericValue & ("fundamental" | "http-server" | "http-client" | "command" | "server" | "modeling" | "test");
+    contract: <GenericContractValue extends string = "fundamental" | "http-server" | "http-client" | "command" | "server" | "modeling" | "test">(...args: (Exclude<"fundamental", GenericContractValue> | Exclude<"http-server", GenericContractValue> | Exclude<"http-client", GenericContractValue> | Exclude<"command", GenericContractValue> | Exclude<"server", GenericContractValue> | Exclude<"modeling", GenericContractValue> | Exclude<"test", GenericContractValue> extends infer InferredMissingValue extends string ? DCommon.IsNever<InferredMissingValue> extends true ? unknown : DCommon.ComputedTypeError<`Enum contract is missing value "${InferredMissingValue}".`> : never) & (Exclude<GenericContractValue, "fundamental" | "http-server" | "http-client" | "command" | "server" | "modeling" | "test"> extends infer InferredUnknownValue extends string ? DCommon.IsNever<InferredUnknownValue> extends true ? unknown : DCommon.ComputedTypeError<`Enum contract contains unknown value "${InferredUnknownValue}".`> : never) extends infer InferredRequirement ? DCommon.IsEqual<InferredRequirement, unknown> extends true ? [] : [] & InferredRequirement : never) => /*elided*/ any;
+};
+type SkillEnum = DCommon.GetEnumValue<typeof SkillEnum>;
+export declare function getSkillsFolder(agentType: AgentTypeEnum): DEither.Error<unknown> | DEither.Success<string & DPath.Path & DPath.Absolute>;
+export declare function getSkillPaths(agentType: AgentTypeEnum, skill: SkillEnum): DEither.Error<unknown> | DEither.Success<{
+    readonly selectedSkillPath: string & DPath.Path & DPath.Absolute;
+    readonly skillsFolder: string & DPath.Path & DPath.Absolute;
+    readonly currentSkillFolder: string & DPath.Path & DPath.Absolute;
+}>;
+export declare function copySkill(agentType: AgentTypeEnum, skill: SkillEnum): Promise<DEither.Error<unknown> | DEither.Left<"file-system-remove-error", DSFile.RemoveErrors> | DEither.Right<"file-system-copy", void> | DEither.Left<"file-system-copy-error", DSFile.CopyErrors>>;
+export declare function symlinkSkill(agentType: AgentTypeEnum, skill: SkillEnum): Promise<DEither.Error<unknown> | DEither.Left<"file-system-remove-error", DSFile.RemoveErrors> | DEither.Left<"file-system-ensure-directory-error", DSFile.EnsureDirectoryErrors> | DEither.Right<"file-system-symlink", void> | DEither.Left<"file-system-symlink-error", DSFile.SymlinkErrors>>;
+export {};

package/dist/bin/skills/skill.mjs

@@ -0,0 +1,60 @@
+import { getPackagePath } from "../packagePath.mjs";
+import * as DCommon from "@duplojs/lang/common";
+import * as DPath from "@duplojs/lang/path";
+import * as DSCommon from "@duplojs/server/common";
+import * as DSFile from "@duplojs/server/file";
+import * as DEither from "@duplojs/lang/either";
+import * as DPattern from "@duplojs/lang/pattern";
+//#region scripts/bin/skills/skill.ts
+const AgentTypeEnum = DCommon.createEnum([
+	"default",
+	"claude",
+	"codex"
+]);
+const SkillEnum = DCommon.createEnum([
+	"fundamental",
+	"http-server",
+	"http-client",
+	"command",
+	"server",
+	"modeling",
+	"test"
+]);
+const agentTypeFolderMapper = {
+	claude: ".claude",
+	codex: ".codex",
+	default: ".agents"
+};
+function getSkillsFolder(agentType) {
+	return DEither.rightPipe(DSCommon.getCurrentWorkDirectory(), (directory) => DPath.resolveRelative([
+		directory,
+		DCommon.cast(agentTypeFolderMapper[agentType]),
+		DCommon.cast("skills")
+	]));
+}
+function getSkillPaths(agentType, skill) {
+	const selectedSkillPath = DPath.resolveRelative([
+		getPackagePath(),
+		DPath.declarePath("skills"),
+		DCommon.cast(skill)
+	]);
+	return DEither.rightPipe(getSkillsFolder(agentType), (skillsFolder) => {
+		const currentSkillFolder = DPath.resolveRelative([skillsFolder, DCommon.cast(`duplojs-${skill}`)]);
+		return {
+			selectedSkillPath,
+			skillsFolder,
+			currentSkillFolder
+		};
+	});
+}
+function removeSkill(path) {
+	return DCommon.asyncPipe(DSFile.remove(path, { recursive: true }), DEither.whenIsLeft(DPattern.matchWithErrorOtherwise({ "file-system-remove-not-found": () => DEither.ok() }, (error) => DEither.left("file-system-remove-error", error))));
+}
+function copySkill(agentType, skill) {
+	return DEither.rightAsyncPipe(getSkillPaths(agentType, skill), ({ selectedSkillPath, currentSkillFolder }) => DEither.rightAsyncPipe(removeSkill(currentSkillFolder), () => DSFile.copy(selectedSkillPath, currentSkillFolder)));
+}
+function symlinkSkill(agentType, skill) {
+	return DEither.rightAsyncPipe(getSkillPaths(agentType, skill), ({ selectedSkillPath, skillsFolder, currentSkillFolder }) => DEither.rightAsyncPipe(DSFile.ensureDirectory(skillsFolder), () => removeSkill(currentSkillFolder), () => DSFile.symlink(selectedSkillPath, currentSkillFolder, { type: "dir" })));
+}
+//#endregion
+export { AgentTypeEnum, SkillEnum, copySkill, getSkillPaths, getSkillsFolder, symlinkSkill };

package/dist/bin/skills/update.d.ts

@@ -0,0 +1,2 @@
+import * as DSCommand from "@duplojs/server/command";
+export declare const updateSkillsCommand: DSCommand.Command<"update">;

package/dist/bin/skills/update.mjs

@@ -0,0 +1,19 @@
+import { AgentTypeEnum, SkillEnum, copySkill, getSkillPaths, symlinkSkill } from "./skill.mjs";
+import * as DSCommand from "@duplojs/server/command";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import * as DSFile from "@duplojs/server/file";
+import * as DEither from "@duplojs/lang/either";
+//#region scripts/bin/skills/update.ts
+const updateSkillsCommand = DSCommand.create("update", {
+	description: "Update installed DuploJS skills, preserving copies and symbolic links",
+	options: [DSCommand.createOption("type", DDataStructure.literal(AgentTypeEnum.toTuple()))]
+}, async ({ options }) => {
+	const agentType = options.type ?? "default";
+	for (const skill of SkillEnum.toTuple()) await DEither.rightAsyncPipe(getSkillPaths(agentType, skill), ({ currentSkillFolder }) => DSFile.linkStat(currentSkillFolder), (stat) => {
+		if (stat.isSymlink) return symlinkSkill(agentType, skill);
+		if (stat.isDirectory) return copySkill(agentType, skill);
+		return DEither.ok();
+	});
+});
+//#endregion
+export { updateSkillsCommand };

package/dist/index.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/docs/API/10-lang/10-array/10-at.ts

@@ -0,0 +1,65 @@
+/**
+ * @title DArray.at
+ *
+ * Lire l’élément situé à un index en reflétant dans le type la possibilité d’une absence.
+ */
+import * as DArray from "@duplojs/lang/array";
+import * as DCommon from "@duplojs/lang/common";
+
+declare const colors: readonly ["red", "green", "blue"];
+
+// Appel classique : l’index couvert renvoie l’union des éléments du tableau.
+const color = DArray.at(colors, 1);
+
+// La valeur obtenue est l’un des trois éléments du tuple.
+type _CheckColor = DCommon.ExpectType<
+	typeof color,
+	"red" | "green" | "blue",
+	"strict"
+>;
+
+// Appel curifié : l’index est fixé dans l’étape du pipe.
+const firstColor = DCommon.pipe(
+	colors,
+	DArray.at(0),
+);
+
+// La valeur obtenue est le premier élément du tuple.
+type _CheckFirstColor = DCommon.ExpectType<
+	typeof firstColor,
+	"red" | "green" | "blue",
+	"strict"
+>;
+
+// Un index littéral hors limites est identifié statiquement.
+const missingColor = DArray.at(colors, 3);
+
+// Un index connu hors limites produit undefined.
+type _CheckMissingColor = DCommon.ExpectType<
+	typeof missingColor,
+	undefined,
+	"strict"
+>;
+
+// Avec un index connu seulement au runtime, l’élément peut être absent.
+declare const index: number;
+const maybeColor = DArray.at(colors, index);
+
+// La sortie contient un élément si l’index est valide, sinon undefined.
+type _CheckMaybeColor = DCommon.ExpectType<
+	typeof maybeColor,
+	"red" | "green" | "blue" | undefined,
+	"strict"
+>;
+
+// Une contrainte de cardinalité permet de supprimer undefined pour les indices garantis.
+declare const names: readonly string[] & DArray.MinElements<2>;
+const guaranteedName = DArray.at(names, 1);
+const maybeName = DArray.at(names, 2);
+
+// Le deuxième élément est garanti ; le troisième ne l’est pas.
+type _CheckConstrainedNames = DCommon.ExpectType<
+	[typeof guaranteedName, typeof maybeName],
+	[string, string | undefined],
+	"strict"
+>;

package/docs/API/10-lang/10-array/10-chunk.ts

@@ -0,0 +1,42 @@
+/**
+ * @title DArray.chunk
+ *
+ * Découper un tableau en sous-tableaux dont la taille ne dépasse pas la limite donnée.
+ */
+import * as DArray from "@duplojs/lang/array";
+import * as DCommon from "@duplojs/lang/common";
+
+const numbers = [1, 2, 3, 4, 5];
+
+// Appel classique : chaque sous-tableau contient au plus deux éléments.
+const result = DArray.chunk(numbers, 2);
+
+// La valeur obtenue est [[1, 2], [3, 4], [5]].
+type _CheckResult = DCommon.ExpectType<
+	typeof result,
+	readonly (readonly number[] & DArray.MinElements<1> & DArray.MaxElements<2>)[],
+	"strict"
+>;
+
+// Appel curifié : la taille est configurée dans l’étape du pipe.
+const piped = DCommon.pipe(
+	numbers,
+	DArray.chunk(3),
+);
+
+// La valeur obtenue est [[1, 2, 3], [4, 5]].
+type _CheckPiped = DCommon.ExpectType<
+	typeof piped,
+	readonly (readonly number[] & DArray.MinElements<1> & DArray.MaxElements<3>)[],
+	"strict"
+>;
+
+// Chaque sous-tableau conserve les contraintes de cardinalité déduites de la taille du chunk.
+declare const constrained: readonly number[] & DArray.MinElements<4>;
+const constrainedResult = DArray.chunk(constrained, 2);
+
+type _CheckConstrained = DCommon.ExpectType<
+	typeof constrainedResult,
+	readonly (readonly number[] & DArray.MinElements<1> & DArray.MaxElements<2>)[],
+	"strict"
+>;

package/docs/API/10-lang/10-array/10-coalescing.ts

@@ -0,0 +1,20 @@
+/**
+ * @title DArray.coalescing
+ *
+ * Convertir une valeur en tableau sans ré-encapsuler une valeur déjà contenue dans un tableau.
+ */
+import * as DArray from "@duplojs/lang/array";
+import type * as DCommon from "@duplojs/lang/common";
+
+// Une valeur simple devient un tuple à un élément.
+const value = DArray.coalescing(42);
+
+// La valeur obtenue est [42].
+type _CheckValue = DCommon.ExpectType<typeof value, readonly [42], "strict">;
+
+// Un tableau est conservé avec sa forme et ses éléments.
+declare const input: readonly [1, 2];
+const array = DArray.coalescing(input);
+
+// La valeur obtenue est [1, 2].
+type _CheckArray = DCommon.ExpectType<typeof array, readonly [1, 2], "strict">;

package/docs/API/10-lang/10-array/10-concat.ts

@@ -0,0 +1,34 @@
+/**
+ * @title DArray.concat
+ *
+ * Ajouter les éléments d’un ou plusieurs tableaux à la fin sans muter le tableau d’entrée.
+ */
+import * as DArray from "@duplojs/lang/array";
+import * as DCommon from "@duplojs/lang/common";
+
+const numbers = [1, 2];
+
+// Appel classique : les tableaux sont fusionnés dans une nouvelle collection.
+const result = DArray.concat(numbers, [3], [4, 5]);
+
+// La valeur obtenue est [1, 2, 3, 4, 5] ; numbers reste inchangé.
+type _CheckResult = DCommon.ExpectType<typeof result, readonly number[], "strict">;
+
+// Appel curifié : les éléments fixes sont fournis dans l’étape du pipe.
+const piped = DCommon.pipe(
+	numbers,
+	DArray.concat([3, 4]),
+);
+
+// La valeur obtenue est [1, 2, 3, 4].
+type _CheckPiped = DCommon.ExpectType<typeof piped, readonly number[], "strict">;
+
+// La contrainte minimale du tableau source est réappliquée au résultat.
+declare const constrained: readonly number[] & DArray.MinElements<2>;
+const constrainedResult = DArray.concat(constrained, [3]);
+
+type _CheckConstrained = DCommon.ExpectType<
+	typeof constrainedResult,
+	readonly number[] & DArray.MinElements<2>,
+	"strict"
+>;

package/docs/API/10-lang/10-array/10-copyWithin.ts

@@ -0,0 +1,34 @@
+/**
+ * @title DArray.copyWithin
+ *
+ * Copier une portion d’un tableau vers une autre position dans une nouvelle copie.
+ */
+import * as DArray from "@duplojs/lang/array";
+import * as DCommon from "@duplojs/lang/common";
+
+const numbers = [1, 2, 3, 4];
+
+// Appel classique : copier les éléments [2, 3] à partir de l’index 0.
+const result = DArray.copyWithin(numbers, 0, 1, 3);
+
+// La valeur obtenue est [2, 3, 3, 4] ; numbers reste inchangé.
+type _CheckResult = DCommon.ExpectType<typeof result, readonly number[], "strict">;
+
+// Appel curifié : la cible et la plage sont fixées dans l’étape du pipe.
+const piped = DCommon.pipe(
+	numbers,
+	DArray.copyWithin(0, 1, 3),
+);
+
+// La valeur obtenue est [2, 3, 3, 4].
+type _CheckPiped = DCommon.ExpectType<typeof piped, readonly number[], "strict">;
+
+// Une borne maximale connue est conservée par la copie transformée.
+declare const constrained: readonly number[] & DArray.MaxElements<4>;
+const constrainedResult = DArray.copyWithin(constrained, 0, 1);
+
+type _CheckConstrained = DCommon.ExpectType<
+	typeof constrainedResult,
+	readonly number[] & DArray.MaxElements<4>,
+	"strict"
+>;

package/docs/API/10-lang/10-array/10-every.ts

@@ -0,0 +1,25 @@
+/**
+ * @title DArray.every
+ *
+ * Vérifier que tous les éléments d’un tableau satisfont un prédicat.
+ */
+import * as DArray from "@duplojs/lang/array";
+import * as DCommon from "@duplojs/lang/common";
+import * as DNumber from "@duplojs/lang/number";
+
+const numbers = [2, 4, 6];
+
+// Appel classique : tous les éléments sont pairs.
+const result = DArray.every(numbers, DNumber.isEven);
+
+// La valeur obtenue est true.
+type _CheckResult = DCommon.ExpectType<typeof result, boolean, "strict">;
+
+// Appel curifié : le prédicat est configuré dans l’étape du pipe.
+const piped = DCommon.pipe(
+	numbers,
+	DArray.every(DNumber.isEven),
+);
+
+// La valeur obtenue est true.
+type _CheckPiped = DCommon.ExpectType<typeof piped, boolean, "strict">;