Abstract Class: BaseFormatter &para;

Returns¶

string | null

contextPropertyItems()¶

protected contextPropertyItems(ast, alsoRenderedKeys?): string[]

Defined in: formatters/src/base-formatter.ts:306

Render @context properties that no dedicated section consumes as Label: value items, so structured context is never silently dropped.

Parameters¶

ast¶

alsoRenderedKeys?¶

readonly string[] = []

Returns¶

string[]

contextTextConsumedByProject()¶

protected contextTextConsumedByProject(ast): boolean

Defined in: formatters/src/base-formatter.ts:259

Whether the @context block's text is consumed by the project/intro fallback. Must mirror the project() and intro() consumption conditions exactly, otherwise the context section would either duplicate the text (predicate too narrow) or drop it entirely (predicate too wide).

Parameters¶

ast¶

Returns¶

boolean

createRenderer()¶

protected createRenderer(options?): ConventionRenderer

Defined in: formatters/src/base-formatter.ts:54

Create a convention renderer for this formatter. Uses the provided convention from options or falls back to the default.

Parameters¶

options?¶

Returns¶

ConventionRenderer

dedent()¶

protected dedent(text): string

Defined in: formatters/src/base-formatter.ts:702

Remove common leading whitespace from all lines (dedent). Handles the case where trim() was already called, causing the first line to lose its indentation while subsequent lines retain theirs. Calculates minimum indent from lines 2+ only.

Parameters¶

text¶

string

Returns¶

string

documentationItem()¶

protected documentationItem(value, defaultText): string | null

Defined in: formatters/src/base-formatter.ts:377

Resolve a documentation-standard entry that accepts either a boolean flag or author-supplied prose. A string value is authoritative and replaces the target's default phrasing, so authored text is never silently discarded.

Parameters¶

value¶

Value | undefined

defaultText¶

string

Returns¶

string | null

extractContextTechStackItems()¶

protected extractContextTechStackItems(props): string[]

Defined in: formatters/src/base-formatter.ts:339

Collect @context tech-stack entries from every supported shape: an explicit techStack list plus the languages/runtime/monorepo properties.

Parameters¶

props¶

Record\<string, Value>

Returns¶

string[]

extractExamples()¶

protected extractExamples(ast): object[]

Defined in: formatters/src/base-formatter.ts:875

Extract examples from the

Parameters¶

ast¶

Returns¶

object[]

Examples¶

block. Returns an array of example definitions with name, input, output, and optional description.

extractSectionWithCodeBlock()¶

protected extractSectionWithCodeBlock(text, header): string | null

Defined in: formatters/src/base-formatter.ts:426

Safe extraction of a section that contains a header + content + code block + content Avoids ReDoS by using string search instead of backtracking regex. Matches pattern: Header ... ...

Parameters¶

text¶

string

Returns¶

string | null

extractSkillExamples()¶

protected extractSkillExamples(skillProps): object[]

Defined in: formatters/src/base-formatter.ts:888

Extract examples from a skill's nested examples property. Returns the same shape as extractExamples.

Parameters¶

skillProps¶

Record\<string, Value>

Returns¶

object[]

extractSkills()¶

protected extractSkills(ast, options?): SkillFileConfig[]

Defined in: formatters/src/base-formatter.ts:1092

Extract skills from the

Parameters¶

ast¶

options?¶

Returns¶

SkillFileConfig[]

Skills¶

block, skipping unsafe names and skills excluded by the target's skill filter.

extractText()¶

protected extractText(content): string

Defined in: formatters/src/base-formatter.ts:89

Extract text from block content.

Parameters¶

content¶

Returns¶

string

findBlock()¶

protected findBlock(ast, name): Block | undefined

Defined in: formatters/src/base-formatter.ts:82

Find a block by name, ignoring internal blocks (starting with __).

Parameters¶

ast¶

name¶

string

Returns¶

Block | undefined

format()¶

abstract format(ast, options?): FormatterOutput

Defined in: formatters/src/base-formatter.ts:33

Transform AST to target format

Parameters¶

formatArray()¶

protected formatArray(arr): string

Defined in: formatters/src/base-formatter.ts:140

Format an array as comma-separated string.

Parameters¶

arr¶

unknown[]

Returns¶

string

formatCanonical()¶

formatCanonical(ast, options?): FormatterOutput

Defined in: formatters/src/base-formatter.ts:41

Canonical entry point for legacy implementations.

Subclasses can override this method to consume ordered canonical entries directly. Until then, keep the compatibility projection isolated here.

Parameters¶

ast¶

CanonicalProgram

options?¶

Formatter.formatCanonical

Returns¶

FormatterOutput

Implementation of¶

formatStandardsList()¶

protected formatStandardsList(items): string[]

Defined in: formatters/src/base-formatter.ts:132

Format standards list from array of values (pass-through). Returns array of strings for rendering as bullet list.

Parameters¶

items¶

Value

Returns¶

string[]

generateSkillFile()¶

protected generateSkillFile(config, options?): FormatterOutput | null

Defined in: formatters/src/base-formatter.ts:1132

Render a skill file at the target's skill base path. Returns null when the target declares no skill support.

Parameters¶

config¶

SkillFileConfig

options?¶

Returns¶

FormatterOutput | null

getArrayElements()¶

protected getArrayElements(content): Value[]

Defined in: formatters/src/base-formatter.ts:164

Extract array elements from block content.

Parameters¶

content¶

Returns¶

Value[]

getBlockArrayElements()¶

protected getBlockArrayElements(block): Value[]

Defined in: formatters/src/base-formatter.ts:187

Parameters¶

block¶

Block

Returns¶

Value[]

getMetaField()¶

protected getMetaField(ast, key): string | undefined

Defined in: formatters/src/base-formatter.ts:154

Get meta field value as string.

Parameters¶

ast¶

key¶

string

Returns¶

string | undefined

getNativeAgentName()¶

protected getNativeAgentName(ast, name): string

Defined in: formatters/src/base-formatter.ts:1012

Return the deterministic native identifier for one agent.

Parameters¶

ast¶

name¶

string

Returns¶

string

getNativeAgentNameMap()¶

protected getNativeAgentNameMap(ast): ReadonlyMap\<string, string>

Defined in: formatters/src/base-formatter.ts:1002

Map all agent names consistently for a target's native files.

Parameters¶

ast¶

Returns¶

ReadonlyMap\<string, string>

getOutputPath()¶

protected getOutputPath(options?): string

Defined in: formatters/src/base-formatter.ts:75

Get the output path, respecting options override.

Parameters¶

options?¶

Returns¶

string

getPrettierOptions()¶

protected getPrettierOptions(options?): Required\<PrettierMarkdownOptions>

Defined in: formatters/src/base-formatter.ts:65

Get resolved Prettier options, merging provided options with defaults.

Parameters¶

options?¶

Returns¶

Required\<PrettierMarkdownOptions>

getProp()¶

protected getProp(content, key): Value | undefined

Defined in: formatters/src/base-formatter.ts:103

Get a specific property from block content.

Parameters¶

content¶

key¶

string

Returns¶

Value | undefined

getProps()¶

protected getProps(content): Record\<string, Value>

Defined in: formatters/src/base-formatter.ts:117

Get all properties from block content.

Parameters¶

content¶

Formatter.getSkillBasePath

Returns¶

Record\<string, Value>

getSkillBasePath()¶

getSkillBasePath(): string | null

Defined in: formatters/src/base-formatter.ts:936

Base path for skills, or null if formatter has no skill support.

Returns¶

string | null

Implementation of¶

getSkillFileName()¶

getSkillFileName(): string | null

Defined in: formatters/src/base-formatter.ts:941

Skill file name, or null if formatter has no skill support.

Returns¶

string | null

Implementation of¶

Formatter.getSkillFileName

humanizeLabel()¶

protected humanizeLabel(value): string

Defined in: formatters/src/base-formatter.ts:412

Convert a camelCase/kebab-case key into a human-readable label.

Parameters¶

value¶

string

Returns¶

string

isSafeAgentName()¶

protected isSafeAgentName(name): boolean

Defined in: formatters/src/base-formatter.ts:995

Check if an agent name is safe for use in file paths.

Parameters¶

name¶

string

Returns¶

boolean

isSafeName()¶

protected isSafeName(name): boolean

Defined in: formatters/src/base-formatter.ts:975

Check if a name is safe for use in file paths. Rejects path traversal sequences and path separators.

Parameters¶

name¶

string

Returns¶

boolean

isSafeSkillName()¶

protected isSafeSkillName(name): boolean

Defined in: formatters/src/base-formatter.ts:988

Check if a skill name is safe for use in file paths.

Parameters¶

name¶

string

Returns¶

boolean

mergeRequiredSkillFrontmatter()¶

protected mergeRequiredSkillFrontmatter(rawFrontmatter, name, description): string

Defined in: formatters/src/base-formatter.ts:1060

Preserve raw skill frontmatter while supplying mandatory skill fields.

Parameters¶

rawFrontmatter¶

string

name¶

string

description¶

string

Returns¶

string

normalizeMarkdownForPrettier()¶

protected normalizeMarkdownForPrettier(content): string

Defined in: formatters/src/base-formatter.ts:454

Normalize markdown content to match Prettier formatting. - Strips common leading indentation from lines - Trims trailing whitespace from lines - Normalizes markdown table formatting - Adds blank lines before lists when preceded by text - Adds blank lines before code blocks when preceded by text - Escapes markdown special characters in paths

Parameters¶

content¶

string

Returns¶

string

normalizeOutputDir()¶

protected normalizeOutputDir(dir): string

Defined in: formatters/src/base-formatter.ts:735

Normalize a user-provided output directory (from @use ... into "<path>" or skillTargets config) to a safe forward-slash relative path. Rejects .., . and leading slashes so the result can be appended to a target's dot-directory without escaping it.

Parameters¶

dir¶

string

Returns¶

string

normalizeResourcePath()¶

protected normalizeResourcePath(relativePath): string | null

Defined in: formatters/src/base-formatter.ts:802

Normalize a resource path to a safe, portable relative path.

Parameters¶

relativePath¶

string

Returns¶

string | null

referenceProvenance()¶

protected referenceProvenance(sourcePath): string

Defined in: formatters/src/base-formatter.ts:967

Generate a provenance comment for a reference file.

Parameters¶

sourcePath¶

string

Returns¶

string

referencesMode()¶

referencesMode(): "none" | "directory" | "inline"

Defined in: formatters/src/base-formatter.ts:951

How this formatter handles skill references. - 'directory': emit as separate files in references/ subdirectory - 'inline': append as sections in the main output file - 'none': references not supported

Returns¶

"none" | "directory" | "inline"

Implementation of¶

Formatter.referencesMode

renderCodeFence()¶

protected renderCodeFence(content, lang?): string

Defined in: formatters/src/base-formatter.ts:1204

Render content inside a code fence, using a longer fence if the content itself contains triple backticks (prevents code fence injection).

Parameters¶

content¶

string

lang?¶

string = ''

Returns¶

string

renderExamplesSection()¶

protected renderExamplesSection(ast, renderer, sectionName?): string | null

Defined in: formatters/src/base-formatter.ts:904

Render an examples section from the

Parameters¶

ast¶

renderer¶

ConventionRenderer

sectionName?¶

string = 'Examples'

Custom section heading name (default: 'Examples')

Returns¶

string | null

Examples¶

block. Shared rendering logic used by Claude, GitHub, and MarkdownInstructionFormatter.

resolveSkillDir()¶

protected resolveSkillDir(defaultSkillBasePath, skillName, outputDir?, options?): string

Defined in: formatters/src/base-formatter.ts:765

Resolve the directory for a generated skill, respecting per-target skill base overrides while preserving existing @use ... into behavior.

Parameters¶

defaultSkillBasePath¶

string

skillName¶

string

outputDir?¶

string

options?¶

Returns¶

string

sanitizeResourceFiles()¶

protected sanitizeResourceFiles(resources, targetDir): FormatterOutput[]

Defined in: formatters/src/base-formatter.ts:821

Filter resource files to only include safe canonical paths.

Parameters¶

resources¶

object[] | undefined

targetDir¶

string

Returns¶

FormatterOutput[]

shortcutSummary()¶

protected shortcutSummary(value, fallback?): string

Defined in: formatters/src/base-formatter.ts:234

Extract a stable one-line summary from any supported shortcut value.

Parameters¶

value¶

Value

fallback?¶

string = ''

Returns¶

string

shouldIncludeSkill()¶

protected shouldIncludeSkill(name, options?): boolean

Defined in: formatters/src/base-formatter.ts:754

Return true when the target configuration allows emitting the given skill.

Parameters¶

name¶

string

options?¶