Skip to content
Generated from the .d.ts files published in guardlink@2.7.1. Report problems against guardlink, not this page.

init

Everything exported by guardlink/init, from the .d.ts files published in guardlink@2.7.1. See the entry points for the other subpaths, and use guardlink as a library for worked examples.

Property Type Description
excluded object[] Extensions present but left out of scope, with counts and the reason.
include string[] -
languages IncludedLanguage[] -
source "git" | "walk" Where the file list came from.

Property Type Description
agentIds? string[] Agents whose instruction files this run may CREATE when they do not exist. Without it, init writes its block only into instruction files that already exist: GuardLink does not add files to a repository it was not asked to.
dryRun? boolean Dry run — show what would be created without writing
force? boolean Re-scaffold an already-initialized project: rewrite config, README, prompt, reference doc, .mcp.json and the agent instruction blocks. It does NOT overwrite authored content. A definitions file holding declarations the template does not, and a config.json carrying settings the template does not, are preserved and reported (D24). Use reset for those.
mode? AnnotationMode Where annotations LIVE. Nothing else. external (default) — .gal sidecars under .guardlink/annotations/ inline — comments in the source files themselves This used to also decide whether init wrote anything outside .guardlink/, which conflated two unrelated questions and made “keep annotations out of my source” cost you MCP auto-discovery and every agent instruction file — the two things that make an agent aware GuardLink exists at all. That footprint question is now rootFiles (GL-506).
model? ThreatModel | null The model as parsed before init ran, when the caller has one. Decides the block’s opening (a repository being re-initialised may already have annotations) and its provenance stamp. Without it the stamp is computed for an empty annotation set, which is what a first init describes.
project? string Override project name
refreshScope? boolean Rewrite include in an existing config.json from the languages present now, leaving every other key as it is. Without it an existing config is never touched for scope: its include may be one a person chose.
reset? boolean Overwrite authored content too — the definitions file and a customised config.json. This DESTROYS the threat model’s declarations. Typing the flag is the confirmation; there is no prompt, because the flag exists so the destructive intent has to be stated separately from “re-scaffold”. Implies force.
root string Project root directory
rootFiles? boolean Whether init may write outside .guardlink/. Default true: root .mcp.json, agent instruction files, docs/, .gitignore and .gitattributes. Set false for a zero-footprint install where .guardlink/ is the entire diff — what --mode external used to imply, now asked for on its own.
skipAgentFiles? boolean Skip agent file updates (only create .guardlink/)

Property Type Description
created string[] -
preserved string[] Files --force declined to overwrite because they hold authored content (D24). Distinct from skipped, which is the ordinary “exists, not forcing” case: an entry here means the user asked for an overwrite and did not get one, so callers are expected to say so loudly.
project ProjectInfo -
scope IncludeScope The include scope detected for this repository, and why.
scopeMissing string[] Globs the detected scope has that an existing, untouched config.json include lacks — languages present that the config does not parse. Empty when the scope was written or nothing is missing.
scopeRefreshOnly boolean True when the only write to config.json was refreshScope’s.
scopeWritten boolean Whether scope.include is what config.json now holds — it was created, re-scaffolded or refreshed by this run. False when an existing include was left alone.
skipped string[] -
updated string[] -

Property Type
dryRun? boolean
model ThreatModel | null
root string

Property Type
skipped string[]
updated string[]

const AGENT_CHOICES: AgentChoice[]

blockStamp(root, model): ModelContextFreshness

The provenance stamp for a block written now: the annotation hash of model (of an empty annotation set when there is none yet, which is what a first init describes) and the hash of what the repository’s agent configuration grants, unless reading it is switched off.

Parameter Type
root string
model ThreatModel | null

ModelContextFreshness


describeScope(scope, maxExcluded?): string[]

The lines init prints to explain the scope it wrote.

Parameter Type
scope IncludeScope
maxExcluded? number

string[]


detectIncludeScope(root, primary): IncludeScope

The include for root: every language present that GuardLink parses.

primary is the language the root manifest names. It is always in scope even with no files yet — a freshly created project keeps the include it had — and when nothing parseable is found and no manifest names a language, the old multi-language fallback stands.

Parameter Type
root string
primary ProjectLanguage

IncludeScope


initProject(options): InitResult

Parameter Type
options InitOptions

InitResult


promptAgentSelection(agentFiles): Promise<string[]>

Show detection-aware prompt. Displays:

  1. Always-created files
  2. Auto-detected agents (from directory presence)
  3. Optional agents user can add

Returns combined list of agent IDs (detected + user-selected).

Parameter Type
agentFiles AgentFile[]

Promise<string[]>


replaceOrAppend(existing, block): string

If markers exist, replace the content between them. Otherwise append to end of file.

The rule, in every file init and sync write into: text outside the markers is preserved byte for byte. Only the block between <!-- guardlink:begin --> and <!-- guardlink:end -->, and the one line break that ends it, are GuardLink’s — except a note another tool appended after GuardLink’s footer line inside the block, which is carried forward (see carryFooterTail).

Parameter Type
existing string
block string

string


resolveAgentFiles(agentIds): AgentChoice[]

Resolve agent IDs (from picker or flags) to file paths.

Parameter Type
agentIds string[]

AgentChoice[]


syncAgentFiles(options): SyncResult

Rewrite the stamped GuardLink block in every agent instruction file that exists. Called after parse/validate/annotate to keep instructions up to date. Uses marker-based replacement so text outside the markers is preserved byte for byte, in every file — .cursor/rules/guardlink.mdc included.

Parameter Type
options SyncOptions

SyncResult

Re-exports AgentFile


Re-exports detectProject


Re-exports ProjectInfo