Create shared utility package

.changeset/config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/[email protected]/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

.changeset/initial-utility.md

@@ -0,0 +1,5 @@
+---
+'@ankhorage/utility': minor
+---
+
+Add the initial shared utility package with project detection and regex subpaths.

.github/workflows/ci.yml

@@ -0,0 +1,53 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: '1.3.13'
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Run build
+        run: bun run build
+
+      - name: Validate Ankhorage repository
+        run: bunx @ankhorage/ankh doctor validate .
+
+      - name: Run lint
+        run: bun run lint
+
+      - name: Run format check
+        run: bun run format:check
+
+      - name: Run Knip
+        run: bun run knip
+
+      - name: Run tests
+        run: bun run test
+
+      - name: Run typecheck
+        run: bun run typecheck
+
+      - name: Check changesets
+        if: github.event_name == 'pull_request'
+        run: bun run changeset:status

.github/workflows/release.yml

@@ -0,0 +1,55 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  pull-requests: write
+  id-token: write
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: '1.3.13'
+
+      - name: Setup Node for npm publishing
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          registry-url: https://registry.npmjs.org
+
+      - name: Update npm
+        run: npm install -g npm@latest
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Build package
+        run: bun run build
+
+      - name: Create release pull request or publish to npm
+        uses: changesets/action@v1
+        with:
+          version: bun run version-packages
+          publish: bunx changeset publish
+          commit: Version Packages
+          title: Version Packages
+        env:
+          GITHUB_TOKEN: ${{ github.token }}

.gitignore

@@ -0,0 +1,6 @@
+node_modules/
+dist/
+paradox/
+coverage/
+*.tsbuildinfo
+.DS_Store

.prettierrc.js

@@ -0,0 +1,5 @@
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+export default require('@ankhorage/devtools/prettier');

AGENTS.md

@@ -0,0 +1,111 @@
+# Agent Guide
+
+## Scope
+
+This file applies to the whole `ankhorage/utility` repository.
+
+`@ankhorage/utility` provides small, runtime-neutral utilities shared across multiple Ankhorage projects and suitable for compatible external consumers.
+
+## Repository facts
+
+- Package name: `@ankhorage/utility`.
+- Runtime/tooling: Bun.
+- Language: TypeScript, ESM, strict mode.
+- Main source root: `src/`.
+- Build output: `dist/`.
+- Public APIs are exposed through explicit package subpaths such as `@ankhorage/utility/project` and `@ankhorage/utility/regex`.
+- README/docs are generated through Paradox where applicable.
+
+## Architectural rules
+
+- Organize utilities by cohesive domain subpaths.
+- Keep domain-core utilities pure and runtime-neutral.
+- Keep filesystem, framework, UI, and platform concerns outside core utility domains unless a dedicated subpath explicitly owns that concern.
+- Represent project detection as composable traits so consumers can apply their own policies.
+- Add new subpaths when functionality is genuinely reusable across projects and belongs to a clear domain.
+- Keep domain-specific business validation in the package that owns that domain.
+
+## Public API rules
+
+- Public exports are explicit and subpath-based.
+- Keep exports narrow and stable.
+- Add public types only when consumers need them directly.
+- Prefer implementation-local types for internal shapes.
+- Update package exports, tests, docs, and changesets together when public API changes.
+- Treat each public subpath as an intentional package contract.
+
+## Project detection rules
+
+`@ankhorage/utility/project` provides pure project-trait detection based on typed manifest data.
+
+- Detect overlapping traits rather than forcing one mutually exclusive project kind.
+- Consider `dependencies`, `devDependencies`, and `peerDependencies` for framework/package signals.
+- Keep filesystem access in callers or future dedicated filesystem-oriented utilities.
+- Keep detection policy separate from consumer policy. For example, `@ankhorage/devtools` may map detected traits to ESLint profiles while other consumers use the full trait set.
+
+## Regex rules
+
+`@ankhorage/utility/regex` contains broadly reusable patterns and related predicates.
+
+- Name patterns according to their actual semantics.
+- Prefer predicates when they provide a clearer consumer API than direct regex access.
+- Keep domain-specific validation with the domain package that owns it.
+
+## Code quality
+
+- Use strict TypeScript.
+- Keep every function at 50 lines or fewer.
+- Keep modules focused and cohesive.
+- Add focused tests for exported behavior.
+- Keep tests deterministic and runnable offline.
+- Preserve runtime neutrality in core utility modules.
+
+## Validation
+
+Run the relevant checks before handing off:
+
+```bash
+bun run build
+bun run lint:fix
+bun run test
+bun run knip
+bun run typecheck
+bun run format:check
+bunx @ankhorage/ankh doctor validate .
+```
+
+Report clearly if any validation step could not be executed.
+
+## Changesets
+
+Add a changeset for published behavior or public API changes, including:
+
+- new public subpaths
+- new exported functions or types
+- changed exported behavior
+- changed package exports
+
+Repository-documentation-only changes generally do not require a changeset.
+
+## Working style for agents
+
+Before coding:
+
+1. inspect the relevant domain subpath and existing exports
+2. identify whether the change belongs in this shared package or in a domain-specific package
+3. identify whether a changeset is required
+
+While coding:
+
+1. keep changes narrow and focused
+2. preserve strict TypeScript and runtime neutrality
+3. keep functions within the 50-line limit
+4. update tests with behavior changes
+5. keep public exports intentional
+
+Before final handoff:
+
+1. run validation or report what could not be run
+2. summarize public API changes
+3. mention the changeset when one is required
+4. mention any follow-up issue needed

CHANGELOG.md

@@ -0,0 +1 @@
+# @ankhorage/utility

README.md

@@ -1 +1,17 @@
-# utility
+<!-- markdownlint-disable MD013 MD033 -->
+<!-- This file is generated by Paradox. Do not edit manually. -->
+
+# @ankhorage/utility
+
+![license: MIT](././paradox/badges/license.svg) ![npm: v0.0.0](././paradox/badges/npm.svg) ![runtime: bun](././paradox/badges/runtime.svg) ![typescript: strict](././paradox/badges/typescript.svg) ![eslint: checked](././paradox/badges/eslint.svg) ![prettier: checked](././paradox/badges/prettier.svg) ![build: checked](././paradox/badges/build.svg) ![tests: checked](././paradox/badges/tests.svg) ![docs: paradox](././paradox/badges/docs.svg)
+
+Shared, runtime-neutral utilities for Ankhorage packages and compatible external projects.
+
+## Generated documentation
+
+- [Interactive documentation app](././paradox/index.html)
+- [Public API reference](././paradox/exports.md)
+- [Component registry](././paradox/components.md)
+- [Architecture overview](././paradox/diagrams/architecture-overview.mmd)
+- [Module relationships](././paradox/diagrams/module-relationships.mmd)
+- [Export graph](././paradox/diagrams/export-graph.mmd)