Imported from wolfstar-project/stars-components (
AGENTS.md). Install upstream withnpx skills add wolfstar-project/stars-components. Copyright stays with the author.
AGENTS.md
Project conventions discovered for stars-components (formerly archid-components).
Stack
- Language: TypeScript (
~7.0.2in every package/example; the rootpackage.jsondevDependency is still pinned to~5.8.3), Node^22.11 || ^24 || >=26(the range required by Changesets v3; published packages still declare>=20). - Package manager:
pnpm(corepack-pinned viapackageManagerin rootpackage.json; Renovate bumps the patch version often — check that file for the exact pin, don't hardcode it here). Workspaces viapnpm-workspace.yaml. - Monorepo runner:
turbo(turbo run build|typecheck). - Bundler:
tsdownper package. - Typecheck:
golar tsc(each package/example has its owngolar.config.ts, and a root one too) —typecheckscripts rungolar tsc -p ../../tsconfig.jsoninstead of baretsc;dev.typecheck.checker: 'auto'instars.configalso picksgolarwhenever the project depends on it,tscotherwise. - Tests:
vitest(workspace config at root). - Lint:
oxlintwithoxlint-tsgolint. - Format:
oxfmt. - Release: Changesets v3 (
@changesets/cli+changesets/actionin CI, see.github/workflows/release.yml). Packages version independently, not in lockstep (.changeset/config.jsonhasfixed: [],linked: []);updateInternalDependencies: patchbumps workspace dependents. Publishes authenticate via npm trusted publishing (OIDC,id-token: write), which also generates provenance attestations automatically — no npm token secret, see.changeset/README.mdfor the required per-package npmjs.com setup. v3 specifics that the config relies on:format: "oxfmt"(v3 replaced theprettieroption withformat, and generated changelogs must satisfyoxfmt --check), andprivatePackages: { version: true, tag: false }(v3 stopped versioning private packages by default — this keeps theexamples/*apps versioned as before). - Deprecation:
@favware/npm-deprecate(driven by.npm-deprecaterc.yml).
Quality gates (in order)
pnpm lintpnpm buildpnpm typecheck(resolves cross-package imports against builtdist/*.d.ts, so it needspnpm buildfirst)pnpm test
Conventions
- Commits: Conventional Commits (
@commitlint/config-conventional);cz-conventional-changelogvia commitizen. - File paths in CI use the npm scope as
--filter @<scope>/<package>for turbo. - Each package declares:
name,author(scope handle),repository.url,bugs.url,homepage,keywords. - 25 publishable
@wolfstar/*packages underpackages/, each with its own independent semver — there is no lockstep version. Merging a changeset (pnpm changeset) tomainmakeschangesets/action(pinned v2, see.github/workflows/release.yml) open/update achore: update changelog and releasePR; merging that PR bumps the affected packages' versions, regenerates their CHANGELOGs (via.changeset/generator.ts), and publishes to npm. Any other push tomaintouchingpackages/orpackage.jsonalso publishes an@nextsnapshot (pnpm publish:snapshot→scripts/publish-snapshot.mjs, which skips the publish when there are no pending changesets becausechangeset versionexits1in that case since v3). pkg.pr.newcontinuous preview releases (.github/workflows/pkg-pr-new.yml): every PR, push tomain, and manual dispatch builds and runspnpm exec pkg-pr-new publish --pnpm './packages/*'(read-onlycontentspermission, no npm publish) so a PR's package versions can be installed for testing before a Changesets release.@wolfstar/cli(thestarsbinary —dev/build/info/codegen/prepare/commands) is a publishable package underpackages/cli. Thestars.configschema and loader (defineConfig/loadStarsConfig) live in their own package,@wolfstar/schema(packages/schema), which@wolfstar/http-frameworkre-exports unchanged as@wolfstar/http-framework/config; both@wolfstar/cliand@wolfstar/http-frameworkdepend on@wolfstar/schema, not on each other's/configexport, so any tool can resolve a project's configuration without pulling in either.@wolfstar/http-frameworkitself depends on@wolfstar/cliand exposes astarsbin (bin/stars.mjs, re-exporting@wolfstar/cli/cli) the waynuxtexposesnuxi's binary —@wolfstar/clihas no install-time dependency on@wolfstar/http-frameworkin return (the same way@nuxt/clihas none onnuxt): its one runtime touch point,@wolfstar/http-framework/auto-imports, is resolved dynamically from the target project atpackages/cli/src/utils/framework-auto-imports.tsinstead of being declared as a dependency, which is what keeps the two packages from depending on each other. See## The stars CLI configurationbelow.- Shareable tooling configs, extracted from this repo's own root config and published for external
@wolfstar/*consumers:@wolfstar/oxlint-config,@wolfstar/oxfmt-config,@wolfstar/eslint-config,@wolfstar/prettier-config, and@wolfstar/eslint-plugin-http-framework(custom oxlint/ESLint rules for@wolfstar/http-frameworkand@wolfstar/plugin-*consumers, namespacedwolfstar/*). This repo's own root.oxlintrc.json/.oxfmtrc.jsonare the source these were extracted from, not consumers of them — the root config is not migrated toextends/depend on the published packages. - i18n:
@wolfstar/plugin-i18next(external, published fromwolfstar-project/plugins) is the standard@wolfstar/http-frameworki18n plugin —@wolfstar/shared-http-piecesconsumes it directly.@wolfstar/http-framework-i18nis deprecated in favour of it (npm description carries aDEPRECATED:prefix, README has a## Migrationsection, and it's dropped from.npm-deprecaterc.ymlso no further@nextsnapshots publish);@wolfstar/i18next-backendremains published ashttp-framework-i18n's backend dependency.@wolfstar/i18next-type-generatoris a CLI (i18next-type-generator <locales-dir> <output.d.ts>) that generates the i18nextCustomTypeOptionsaugmentation from locale JSON, replacing hand-maintainedLanguageKeys/T/FThelpers; consuming packages wire it up via agenerate:i18nscript (seepackages/shared-http-pieces/package.json). - Logging:
@wolfstar/http-frameworknow has a built-in logger (container.logger), so@wolfstar/loggeris deprecated the same way@wolfstar/http-framework-i18nwas — npm description prefixedDEPRECATED:, README carries a migration warning, dropped from.npm-deprecaterc.yml— in favour of a future@wolfstar/plugin-logger(not published yet, only proposed). - Tolgee sync is configured at root (
.tolgeerc.cjs) and only targetspackages/shared-http-pieces/src/locales/**. Scripts:pnpm tolgee:push(baseen),pnpm tolgee:pull(pull + remap),pnpm tolgee:ensure-languages. Discord locale folders (en-US, es-ES, …) map to shorter Tolgee tags (en, es, …); seeLOCALE_MAPin.tolgeerc.cjs. Project Shared HTTP Pieces (33773) has Tolgee namespaces disabled — keys live in the default namespace and remap intocommands/shared.json.
The stars CLI configuration
- A project's build lives in
stars.config.*, not in a separatetsdown.config.ts:tsdown: {}(andvite: {}forbuild.tool: 'vite') is merged into what the CLI derives fromentry/build. The packages of this repository are libraries and keep their owntsdown.config.ts— this is about the bot projects the CLI builds. future: { compatibilityVersion: 3 | 4 }mirrors Nuxt's own:4is the default as of the convention-first rework (#182,@wolfstar/http-frameworkmajor) —tsdownconfigured fromstars.configalone, auto imports on and wired in,'auto'pickingtsdownfor TypeScript entries.3is legacy behaviour (atsdown.config.*drives the build, auto imports off unless asked for) and was kept as an opt-in rather than dropped:LEGACY_COMPATIBILITY_VERSION(3) stays inCOMPATIBILITY_VERSIONSalongsideLATEST_COMPATIBILITY_VERSION/DEFAULT_COMPATIBILITY_VERSION(4) inpackages/schema/src/config/resolve.ts, and thebuild.configFilebranch (compatibility version 3's file mode) stays inTsdownBuilderand its test.- Convention-first defaults (#182) beyond the compatibility version:
stars devforcesNODE_ENV=developmentfor config evaluation, build plugins, and the supervised process;src/localesis copied to the build output and kept in sync by achokidarwatcher (packages/cli/src/utils/locales.ts) instead of a hand-writtentsdownplugin; and@wolfstar/env-utilities'setup()(aliasedenvRunin scaffoldedsrc/lib/setup/all.ts) takes no argument, discovering.env*files under bothsrc/and the project root itself.@wolfstar/create-http-frameworknow scaffolds a baredefineConfig({})(or{ build: { tool: 'tsc' } }for atscproject) instead of specifyingentry/build/future.
Branding (target state after rebrand)
- npm scope:
@wolfstar - GitHub org:
wolfstar-project - Repo name:
stars-components(already renamed locally; remote URLs must follow) - Primary domain:
wolfstar.rocks(subdomains:join.,donate.,cdn.,influxdb.,contact@) - CI secret:
WOLFSTAR_TOKEN - Influx org string:
Wolfstar-Project - CDN asset path:
cdn.wolfstar.rocks/wolfstar-assets/...
Out of scope for the rebrand
- Per-project Tolgee badge slugs on Crowdin-era READMEs are replaced by a generic Tolgee badge.
The Tolgee project is Shared HTTP Pieces (
projectId33773in.tolgeerc.cjs).
Notes for agents
- Do NOT touch
pnpm-lock.yamlmanually; letpnpm installregenerate it afterpackage.jsonedits. - Do not edit
package.json#versionor a package'sCHANGELOG.mdby hand; both are owned by Changesets. Add a changeset viapnpm changesetfor any user-facing change instead. Manual/hotfix publishes are done by re-running theReleaseworkflow viaworkflow_dispatch. - Folder names under
packages/do not containskyra; only packagename,author, scoped imports, andkeywordsneed updating. - The docs site was moved out of this repo to
wolfstar-project/website; don't reintroduce a docs app ornetlify.tomlhere. pnpm lint/pnpm lint:fixrunoxlint/oxfmtacross bothpackagesandexamples; keep the runnable example apps underexamples/*lint-clean too.
Cursor Cloud specific instructions
- This repo is a library monorepo (25 publishable
@wolfstar/*packages, seepackages/). There is no app/server/GUI to run; "running" the product means exercising packages via the quality gates and/or importing builtdist/outputs. - Dependencies are pre-installed by the startup update script (
pnpm install --frozen-lockfile). Standard commands live in rootpackage.json:pnpm lint,pnpm build,pnpm typecheck,pnpm test. - Run
pnpm buildbeforepnpm typecheck.typecheckresolves cross-package imports (e.g.@wolfstar/env-utilities) against each package's builtdist/*.d.ts; without a prior build,golar tscfails withTS2307: Cannot find module. CI's "Build & Typecheck" job runs build then typecheck for this reason. - Node: CI and
mise.tomlpin Node 24; rootenginesrequire^22.11 || ^24 || >=26. The VM's default Node (v22.x via/exec-daemon/node) satisfies that and works for all gates.pnpmis provided via corepack, pinned by thepackageManagerfield in rootpackage.json(check that file for the current exact version; Renovate bumps it often).
Server integration packages
@wolfstar/vite-serverand@wolfstar/nitro-serverown the optional Vite/Nitro builders. They depend on the sharedBuilder/BuilderContextcontract in@wolfstar/schema, never on@wolfstar/clior the framework.- The CLI's builder adapters supply project-relative loading and plugin registration. Keep optional integrations lazy-loaded by the builder factory; Vite and Nitro themselves are resolved from the consuming project.
- CLI integration tests alias both packages to source so CI can run tests before a build.
