@danieljvdm/dev-kit 0.2.0

package/skills/effect-ts/references/version-and-source.md

@@ -0,0 +1,87 @@
+# Effect Version And Source Strategy
+
+Use this guide before installing Effect packages or relying on exact API names,
+signatures, exports, or source paths.
+
+## Review Baseline
+
+This skill was last reviewed on 2026-07-29 against:
+
+- `effect@4.0.0-beta.102`
+- matching `4.0.0-beta.102` releases of the v4 `@effect/*` packages
+- canonical source from `Effect-TS/effect`
+- official Effect skill commit
+  `a8b6bb40d1d4d550b49c0ff7a624b5e6da500a24`
+
+The beta is intentionally volatile. Review metadata records what was checked;
+it does not override the target repository's installed version.
+
+## Determine The Target Version
+
+Before editing:
+
+1. Read the target repository's package manifest and lockfile.
+2. Identify the resolved `effect` version and every installed `@effect/*`
+   version.
+3. Determine whether the repository is on Effect v3 or the v4 beta.
+4. Keep guidance and source research on that same release line.
+
+Do not silently upgrade an existing repository. If its Effect packages are
+misaligned, report the mismatch and treat version alignment as a separate
+change.
+
+## Installing Effect v4
+
+For a new Effect v4 installation:
+
+1. Resolve the current `effect@beta` version from the package registry.
+2. Install `effect` at that exact version.
+3. Install only the runtime and integration packages the task requires.
+4. Pin every v4 `@effect/*` package to the same exact beta version.
+
+`effect@latest` is the stable v3 release line until Effect v4 leaves beta.
+Do not use generic v3 packages such as `@effect/platform` with Effect v4.
+Effect v4 places many capabilities under `effect/unstable/*`; install separate
+packages only for runtime-, provider-, driver-, or tool-specific integrations.
+
+## Source Research
+
+Use this order:
+
+1. Search the installed package declarations and source in the target
+   repository.
+2. Check the target repository for established usage of the same API.
+3. Inspect the canonical `Effect-TS/effect` source at the matching tag or
+   commit.
+4. Use current `main` only when intentionally researching a future upgrade.
+
+A project-local checkout at canonical `Effect-TS/effect` source may be used when the repository
+already provides one, but it is optional. Never pause ordinary Effect work to
+force the user to add a subtree, submodule, or clone.
+
+## V4 Migration Checks
+
+When adapting older examples, verify them against the installed v4 release.
+Common v4 changes include:
+
+- define services with `Context.Service`, not the removed `Context.Tag`,
+  `Context.GenericTag`, `Effect.Tag`, or `Effect.Service`
+- prefer yielding the service key directly
+- use `Effect.catch`, `Effect.catchCause`, and `Effect.catchFilter` rather than
+  the renamed v3 `catchAll`, `catchAllCause`, and `catchSome`
+- use `Context` plus `Effect.runForkWith` rather than the removed generic
+  `Runtime<R>` and `Effect.runtime`
+- import consolidated capabilities from `effect/unstable/*` rather than
+  obsolete standalone packages
+- verify Schema class, union, decoding, and transformation signatures because
+  they changed throughout the v4 beta
+
+## Completion Check
+
+Before completing version-sensitive work:
+
+- every code example uses APIs present in the target's resolved packages
+- every installed Effect v4 package resolves to the same beta
+- no source path is assumed solely because it appears in this skill
+- current-main guidance is not presented as installed-version behavior
+

package/src/bin/dev-kit.ts

@@ -0,0 +1,372 @@
+import { NodeRuntime, NodeServices } from "@effect/platform-node";
+import { Argument, CliError, Command as CliCommand, Flag } from "effect/unstable/cli";
+import { Effect, Result } from "effect";
+
+import { printError } from "../cli-ui.ts";
+import { patchEffectTsgo } from "../effect-tsgo.ts";
+import { syncEffectSource } from "../effect-source.ts";
+import { patchProjectGitignore } from "../gitignore.ts";
+import {
+  DEFAULT_MANIFEST,
+  runProjectSkillPlan,
+} from "../sync.ts";
+import { DEV_KIT_VERSION } from "../tool-metadata.ts";
+import { refreshSkillCatalog } from "../vendor.ts";
+import {
+  addCatalogSource,
+  listCatalogSources,
+  removeCatalogEntry,
+  showCatalogSource,
+} from "../catalog-manager.ts";
+import {
+  addSkills,
+  chooseSkillsToAdd,
+  chooseSkillsToRemove,
+  initProject,
+  listSkills,
+  removeSkills,
+  showDashboard,
+  showSkill,
+} from "../skill-manager.ts";
+
+const projectFlags = {
+  manifest: Flag.string("manifest").pipe(
+    Flag.withDefault(DEFAULT_MANIFEST),
+    Flag.withDescription("Project-relative manifest path."),
+  ),
+  projectDir: Flag.string("project-dir").pipe(
+    Flag.withDefault("."),
+    Flag.withDescription("Project directory (defaults to the current directory)."),
+  ),
+};
+
+const initCommand = CliCommand.make("init", projectFlags, ({ manifest, projectDir }) =>
+  initProject({ manifestPath: manifest, projectDir }),
+).pipe(CliCommand.withDescription("Initialize skill management in this project."));
+
+const addCommand = CliCommand.make(
+  "add",
+  {
+    skills: Argument.string("skills").pipe(Argument.variadic()),
+    noApply: Flag.boolean("no-apply").pipe(
+      Flag.withDescription("Update the manifest without installing yet."),
+    ),
+    ...projectFlags,
+  },
+  ({ skills, noApply, manifest, projectDir }) =>
+    skills.length === 0
+      ? chooseSkillsToAdd({ apply: !noApply, manifestPath: manifest, projectDir })
+      : addSkills(skills, { apply: !noApply, manifestPath: manifest, projectDir }),
+).pipe(CliCommand.withDescription("Select and install one or more approved skills."));
+
+const removeCommand = CliCommand.make(
+  "remove",
+  {
+    skills: Argument.string("skills").pipe(Argument.variadic()),
+    noApply: Flag.boolean("no-apply").pipe(
+      Flag.withDescription("Update the manifest without uninstalling yet."),
+    ),
+    ...projectFlags,
+  },
+  ({ skills, noApply, manifest, projectDir }) =>
+    skills.length === 0
+      ? chooseSkillsToRemove({ apply: !noApply, manifestPath: manifest, projectDir })
+      : removeSkills(skills, { apply: !noApply, manifestPath: manifest, projectDir }),
+).pipe(CliCommand.withDescription("Deselect and uninstall one or more skills."));
+
+const listCommand = CliCommand.make(
+  "list",
+  {
+    all: Flag.boolean("all").pipe(Flag.withDescription("Include unselected skills.")),
+    ...projectFlags,
+  },
+  ({ all, manifest, projectDir }) =>
+    listSkills({ all, manifestPath: manifest, projectDir }),
+).pipe(CliCommand.withDescription("List selected skills; use --all to browse the catalog."));
+
+const searchCommand = CliCommand.make(
+  "search",
+  { query: Argument.string("query").pipe(Argument.variadic({ min: 1 })), ...projectFlags },
+  ({ query, manifest, projectDir }) =>
+    listSkills({ all: true, query: query.join(" "), manifestPath: manifest, projectDir }),
+).pipe(CliCommand.withDescription("Search approved skill names and descriptions."));
+
+const infoCommand = CliCommand.make(
+  "info",
+  { skill: Argument.string("skill") },
+  ({ skill }) => showSkill(skill),
+).pipe(CliCommand.withDescription("Show provenance and details for an approved skill."));
+
+const planCommand = CliCommand.make(
+  "plan",
+  {
+    locked: Flag.boolean("locked"),
+    lockfile: Flag.string("lockfile").pipe(Flag.withDefault("dev-kit.lock.json")),
+    manifest: Flag.string("manifest").pipe(Flag.withDefault(DEFAULT_MANIFEST)),
+    projectDir: Flag.string("project-dir").pipe(Flag.withDefault(".")),
+  },
+  ({ locked, lockfile, manifest, projectDir }) =>
+    runProjectSkillPlan({
+      dryRun: true,
+      locked,
+      lockfilePath: lockfile,
+      manifestPath: manifest,
+      projectDir,
+    }),
+).pipe(CliCommand.withDescription("Plan ownership-safe project skill changes without writing files."));
+
+const applyCommand = CliCommand.make(
+  "apply",
+  {
+    locked: Flag.boolean("locked"),
+    lockfile: Flag.string("lockfile").pipe(Flag.withDefault("dev-kit.lock.json")),
+    manifest: Flag.string("manifest").pipe(Flag.withDefault(DEFAULT_MANIFEST)),
+    projectDir: Flag.string("project-dir").pipe(Flag.withDefault(".")),
+  },
+  ({ locked, lockfile, manifest, projectDir }) =>
+    runProjectSkillPlan({
+      locked,
+      lockfilePath: lockfile,
+      manifestPath: manifest,
+      projectDir,
+    }),
+).pipe(CliCommand.withDescription("Apply ownership-safe project skill changes and update the lock."));
+
+const syncCommand = CliCommand.make(
+  "sync",
+  {
+    locked: Flag.boolean("locked"),
+    lockfile: Flag.string("lockfile").pipe(Flag.withDefault("dev-kit.lock.json")),
+    ...projectFlags,
+  },
+  ({ locked, lockfile, manifest, projectDir }) =>
+    runProjectSkillPlan({ locked, lockfilePath: lockfile, manifestPath: manifest, projectDir }),
+).pipe(CliCommand.withDescription("Install the skills selected in dev-kit.jsonc."));
+
+const statusCommand = CliCommand.make(
+  "status",
+  {
+    lockfile: Flag.string("lockfile").pipe(Flag.withDefault("dev-kit.lock.json")),
+    ...projectFlags,
+  },
+  ({ lockfile, manifest, projectDir }) =>
+    runProjectSkillPlan({
+      dryRun: true,
+      lockfilePath: lockfile,
+      manifestPath: manifest,
+      projectDir,
+    }),
+).pipe(CliCommand.withDescription("Check whether selected skills match the project."));
+
+const gitignoreCommand = CliCommand.make(
+  "gitignore",
+  {
+    dryRun: Flag.boolean("dry-run"),
+    projectDir: Flag.string("project-dir").pipe(Flag.withDefault(".")),
+  },
+  ({ dryRun, projectDir }) => patchProjectGitignore({ dryRun, projectDir }),
+).pipe(
+  CliCommand.withDescription(
+    "Idempotently add .repos/ and .dev-kit/ to the project .gitignore.",
+  ),
+);
+
+const tsgoPatchCommand = CliCommand.make(
+  "patch",
+  {
+    dryRun: Flag.boolean("dry-run"),
+    force: Flag.boolean("force"),
+    projectDir: Flag.string("project-dir").pipe(Flag.withDefault(".")),
+    typescriptPackage: Flag.string("typescript-package").pipe(
+      Flag.withDefault("typescript"),
+    ),
+  },
+  ({ dryRun, force, projectDir, typescriptPackage }) =>
+    patchEffectTsgo({ dryRun, force, projectDir, typescriptPackage }),
+).pipe(
+  CliCommand.withDescription(
+    "Patch the project-local native TypeScript compiler with the pinned Effect language service.",
+  ),
+);
+
+const tsgoCommand = CliCommand.make("tsgo").pipe(
+  CliCommand.withDescription("Manage the pinned Effect TypeScript-Go integration."),
+  CliCommand.withSubcommands([tsgoPatchCommand] as const),
+);
+
+const effectSyncCommand = CliCommand.make(
+  "sync",
+  {
+    dryRun: Flag.boolean("dry-run"),
+    packageName: Flag.string("package").pipe(Flag.withDefault("effect")),
+    path: Flag.string("path").pipe(Flag.withDefault(".repos/effect")),
+    projectDir: Flag.string("project-dir").pipe(Flag.withDefault(".")),
+    repository: Flag.string("repository").pipe(
+      Flag.withDefault("https://github.com/Effect-TS/effect.git"),
+    ),
+  },
+  ({ dryRun, packageName, path, projectDir, repository }) =>
+    syncEffectSource({
+      dryRun,
+      packageName,
+      path,
+      projectDir,
+      repository,
+    }),
+).pipe(
+  CliCommand.withDescription(
+    "Sync a detached Effect source checkout to the installed package version.",
+  ),
+);
+
+const effectCommand = CliCommand.make("effect").pipe(
+  CliCommand.withDescription("Manage the version-matched Effect source checkout."),
+  CliCommand.withSubcommands([effectSyncCommand] as const),
+);
+
+const catalogFilesFlags = {
+  lockfile: Flag.string("lockfile").pipe(
+    Flag.withDefault("skill-sources.lock.json"),
+    Flag.withDescription("Approved catalog snapshot path."),
+  ),
+  repoDir: Flag.string("repo-dir").pipe(
+    Flag.withDefault("."),
+    Flag.withDescription("Catalog repository directory."),
+  ),
+  sources: Flag.string("sources").pipe(
+    Flag.withDefault("skill-sources.jsonc"),
+    Flag.withDescription("Authored source manifest path."),
+  ),
+};
+
+const catalogAddCommand = CliCommand.make(
+  "add",
+  {
+    repository: Argument.string("repository"),
+    all: Flag.boolean("all").pipe(
+      Flag.withDescription("Approve every skill discovered in this snapshot."),
+    ),
+    dryRun: Flag.boolean("dry-run").pipe(Flag.withDescription("Inspect without writing.")),
+    id: Flag.string("id").pipe(Flag.withDefault(""), Flag.withDescription("Override the inferred source id.")),
+    license: Flag.string("license").pipe(Flag.withDefault(""), Flag.withDescription("Repository-relative license path.")),
+    ref: Flag.string("ref").pipe(Flag.withDefault(""), Flag.withDescription("Branch, tag, or commit to track.")),
+    skill: Flag.string("skill").pipe(
+      Flag.atLeast(0),
+      Flag.withDescription("Approve one skill; repeat for several."),
+    ),
+    skillsPath: Flag.string("skills-path").pipe(
+      Flag.withDefault(""),
+      Flag.withDescription("Repository-relative directory containing skills."),
+    ),
+    stripFrontmatter: Flag.string("strip-frontmatter").pipe(
+      Flag.atLeast(0),
+      Flag.withDescription("Remove an upstream frontmatter key; repeat for several."),
+    ),
+    ...catalogFilesFlags,
+  },
+  ({ repository, all, dryRun, id, license, ref, skill, skillsPath, stripFrontmatter, lockfile, repoDir, sources }) =>
+    addCatalogSource({
+      repository,
+      all,
+      dryRun,
+      skills: skill,
+      stripFrontmatter,
+      lockfilePath: lockfile,
+      repoDir,
+      sourcesPath: sources,
+      ...(id ? { id } : {}),
+      ...(license ? { licensePath: license } : {}),
+      ...(ref ? { ref } : {}),
+      ...(skillsPath ? { skillsPath } : {}),
+    }),
+).pipe(CliCommand.withDescription("Inspect a repository and approve selected skills."));
+
+const catalogListCommand = CliCommand.make(
+  "list",
+  catalogFilesFlags,
+  ({ lockfile, repoDir, sources }) =>
+    listCatalogSources({ lockfilePath: lockfile, repoDir, sourcesPath: sources }),
+).pipe(CliCommand.withDescription("List approved upstream repositories."));
+
+const catalogInfoCommand = CliCommand.make(
+  "info",
+  { source: Argument.string("source"), ...catalogFilesFlags },
+  ({ source, lockfile, repoDir, sources }) =>
+    showCatalogSource(source, { lockfilePath: lockfile, repoDir, sourcesPath: sources }),
+).pipe(CliCommand.withDescription("Show an approved source and its skills."));
+
+const catalogRemoveCommand = CliCommand.make(
+  "remove",
+  {
+    entry: Argument.string("source-or-skill"),
+    dryRun: Flag.boolean("dry-run").pipe(Flag.withDescription("Preview without writing.")),
+    yes: Flag.boolean("yes").pipe(Flag.withDescription("Confirm catalog revocation.")),
+    ...catalogFilesFlags,
+  },
+  ({ entry, dryRun, yes, lockfile, repoDir, sources }) =>
+    removeCatalogEntry(entry, { dryRun, yes, lockfilePath: lockfile, repoDir, sourcesPath: sources }),
+).pipe(CliCommand.withDescription("Revoke an approved source or individual skill."));
+
+const catalogRefreshCommand = CliCommand.make(
+  "refresh",
+  {
+    dryRun: Flag.boolean("dry-run").pipe(Flag.withDescription("Preview without writing.")),
+    locked: Flag.boolean("locked").pipe(Flag.withHidden),
+    ...catalogFilesFlags,
+  },
+  ({ dryRun, locked, lockfile, repoDir, sources }) =>
+    refreshSkillCatalog({ dryRun, locked, lockfilePath: lockfile, repoDir, sourcesPath: sources }),
+).pipe(CliCommand.withDescription("Approve the current upstream refs as an exact catalog snapshot."));
+
+const catalogVerifyCommand = CliCommand.make(
+  "verify",
+  catalogFilesFlags,
+  ({ lockfile, repoDir, sources }) =>
+    refreshSkillCatalog({ locked: true, lockfilePath: lockfile, repoDir, sourcesPath: sources }),
+).pipe(CliCommand.withDescription("Verify the committed catalog without advancing refs."));
+
+const catalogCommand = CliCommand.make("catalog").pipe(
+  CliCommand.withDescription("Maintain the approved upstream catalog."),
+  CliCommand.withSubcommands([
+    catalogAddCommand,
+    catalogRemoveCommand,
+    catalogListCommand,
+    catalogInfoCommand,
+    catalogRefreshCommand,
+    catalogVerifyCommand,
+  ] as const),
+);
+
+const command = CliCommand.make("dev-kit", projectFlags, ({ manifest, projectDir }) =>
+  showDashboard({ manifestPath: manifest, projectDir }),
+).pipe(
+  CliCommand.withDescription("Your approved skill catalog for coding agents."),
+  CliCommand.withSubcommands([
+    {
+      group: "Skills",
+      commands: [initCommand, addCommand, removeCommand, listCommand, searchCommand, infoCommand],
+    },
+    { group: "Project", commands: [statusCommand, syncCommand] },
+    {
+      group: "Advanced",
+      commands: [planCommand, applyCommand, gitignoreCommand, effectCommand, tsgoCommand, catalogCommand],
+    },
+  ] as const),
+);
+
+const program = CliCommand.run(command, { version: DEV_KIT_VERSION }).pipe(
+  Effect.catchFilter(
+    (error) =>
+      CliError.isCliError(error) && error._tag === "ShowHelp"
+        ? Result.fail(error)
+        : Result.succeed(error),
+    (error) =>
+      printError(error instanceof Error ? error.message : String(error)).pipe(
+        Effect.andThen(Effect.fail(error)),
+      ),
+  ),
+  Effect.scoped,
+  Effect.provide(NodeServices.layer),
+);
+
+NodeRuntime.runMain(program, { disableErrorReporting: true });