Markdown Imports Implementation Plan¶

it('should tokenize RelativePath with .md extension', () => {
  const result = tokenize('./skills/frontend-design.md');
  expect(result.tokens).toHaveLength(1);
  expect(result.tokens[0]?.tokenType.name).toBe('RelativePath');
  expect(result.tokens[0]?.image).toBe('./skills/frontend-design.md');
});

it('should tokenize RelativePath with ../ prefix and .md extension', () => {
  const result = tokenize('../shared/security-scan.md');
  expect(result.tokens).toHaveLength(1);
  expect(result.tokens[0]?.tokenType.name).toBe('RelativePath');
  expect(result.tokens[0]?.image).toBe('../shared/security-scan.md');
});

it('should tokenize RelativePath with mid-segment dots', () => {
  const result = tokenize('./some.dir/file.prs');
  expect(result.tokens).toHaveLength(1);
  expect(result.tokens[0]?.tokenType.name).toBe('RelativePath');
  expect(result.tokens[0]?.image).toBe('./some.dir/file.prs');
});

export const RelativePath = createToken({
  name: 'RelativePath',
  pattern: /\.\/[a-zA-Z0-9_/.-]+|\.\.\/[a-zA-Z0-9_/.-]+/,
});

it('should tokenize PathReference with .md extension', () => {
  const result = tokenize('@org/skills/frontend-design.md');
  expect(result.tokens).toHaveLength(1);
  expect(result.tokens[0]?.tokenType.name).toBe('PathReference');
  expect(result.tokens[0]?.image).toBe('@org/skills/frontend-design.md');
});

it('should tokenize PathReference with .md and version', () => {
  const result = tokenize('@org/skills/frontend-design.md@2.1.0');
  expect(result.tokens).toHaveLength(1);
  expect(result.tokens[0]?.tokenType.name).toBe('PathReference');
  expect(result.tokens[0]?.image).toBe('@org/skills/frontend-design.md@2.1.0');
});

export const PathReference = createToken({
  name: 'PathReference',
  pattern: /@[a-zA-Z_][a-zA-Z0-9_-]*\/[a-zA-Z0-9_/.-]*(?:@[a-zA-Z0-9^~./-]+)?/,
});

it('should allow LockfileDependency with source field', () => {
  const dep: LockfileDependency = {
    version: '1.0.0',
    commit: 'abc123',
    integrity: 'sha256-xyz',
    source: 'md',
  };
  expect(dep.source).toBe('md');
});

it('should allow LockfileDependency without new optional fields', () => {
  const dep: LockfileDependency = {
    version: '1.0.0',
    commit: 'abc123',
    integrity: 'sha256-xyz',
  };
  expect(dep.source).toBeUndefined();
});

export interface LockfileDependency {
  /** Resolved version (tag name or branch) */
  version: string;
  /** Exact commit hash */
  commit: string;
  /** Content integrity hash */
  integrity: string;
  /** Source discriminator for .md-sourced dependencies */
  source?: 'md';
  /** ISO timestamp of last fetch (informational) */
  fetchedAt?: string;
  /** Discovered skill names for directory imports (advisory) */
  skills?: string[];
}

import { describe, it, expect } from 'vitest';
import { makeBlock, makeObjectContent, makeTextContent, VIRTUAL_LOC } from '../ast-factory.js';

describe('ast-factory', () => {
  describe('makeObjectContent', () => {
    it('should create ObjectContent with properties', () => {
      const result = makeObjectContent({ foo: 'bar' });
      expect(result.type).toBe('ObjectContent');
      expect(result.properties).toEqual({ foo: 'bar' });
      expect(result.loc).toEqual(VIRTUAL_LOC);
    });
  });

  describe('makeTextContent', () => {
    it('should create TextContent with value', () => {
      const result = makeTextContent('hello world');
      expect(result.type).toBe('TextContent');
      expect(result.value).toBe('hello world');
    });
  });

  describe('makeBlock', () => {
    it('should create Block with ObjectContent', () => {
      const content = makeObjectContent({ key: 'value' });
      const result = makeBlock('skills', content);
      expect(result.type).toBe('Block');
      expect(result.name).toBe('skills');
      expect(result.content).toBe(content);
    });
  });
});

import type { Block, ObjectContent, TextContent, Value, SourceLocation } from '@promptscript/core';

/** Virtual source location for synthesized AST nodes. */
export const VIRTUAL_LOC: SourceLocation = {
  file: '<synthesized>',
  line: 1,
  column: 1,
  offset: 0,
};

/** Synthesize an ObjectContent node from a properties record. */
export function makeObjectContent(properties: Record<string, Value>): ObjectContent {
  return {
    type: 'ObjectContent',
    properties,
    loc: VIRTUAL_LOC,
  };
}

/** Synthesize a TextContent node. */
export function makeTextContent(value: string, file?: string): TextContent {
  return {
    type: 'TextContent',
    value,
    loc: file ? { file, line: 1, column: 1, offset: 0 } : VIRTUAL_LOC,
  };
}

/** Synthesize a Block node. */
export function makeBlock(name: string, content: ObjectContent | TextContent): Block {
  return {
    type: 'Block',
    name,
    content,
    loc: VIRTUAL_LOC,
  };
}

export { makeBlock, makeObjectContent, makeTextContent, VIRTUAL_LOC } from './ast-factory.js';

import { describe, it, expect } from 'vitest';
import { detectContentType } from '../content-detector.js';

describe('detectContentType', () => {
  it('should detect PRS content when @identity is at start of line', () => {
    const content = '@identity {\n  role: "developer"\n}';
    expect(detectContentType(content)).toBe('prs');
  });

  it('should detect skill when YAML frontmatter is present', () => {
    const content = '---\nname: my-skill\ndescription: A skill\n---\nSkill body here';
    expect(detectContentType(content)).toBe('skill');
  });

  it('should detect raw when no frontmatter and no PRS blocks', () => {
    const content = '# My Skill\n\nDo something useful.';
    expect(detectContentType(content)).toBe('raw');
  });

  it('should NOT detect PRS when @identity is inside fenced code block', () => {
    const content = '# Guide\n\n```promptscript\n@identity {\n  role: "x"\n}\n```\n';
    expect(detectContentType(content)).toBe('raw');
  });

  it('should NOT detect PRS when @identity is inside ~~~ fence', () => {
    const content = '# Guide\n\n~~~\n@identity {\n  role: "x"\n}\n~~~\n';
    expect(detectContentType(content)).toBe('raw');
  });

  it('should NOT detect PRS when only @skills without @identity', () => {
    const content = '@skills {\n  foo: { description: "x" }\n}';
    expect(detectContentType(content)).toBe('raw');
  });

  it('should detect PRS over skill when both @identity and frontmatter', () => {
    const content = '---\nname: x\n---\n@identity {\n  role: "y"\n}';
    expect(detectContentType(content)).toBe('prs');
  });

  it('should handle fenced code with language identifier', () => {
    const content = '```typescript\n@identity { role: "x" }\n```\n';
    expect(detectContentType(content)).toBe('raw');
  });

  it('should handle BOM prefix', () => {
    const content = '\uFEFF---\nname: skill\n---\nBody';
    expect(detectContentType(content)).toBe('skill');
  });

  it('should return raw for empty content', () => {
    expect(detectContentType('')).toBe('raw');
  });
});

/**
 * Content type detection for .md files.
 *
 * Determines how a .md file should be processed:
 * - 'prs': Contains @identity block outside fenced code → parse as PromptScript
 * - 'skill': Has YAML frontmatter (---) → parse with parseSkillMd()
 * - 'raw': Plain markdown → create synthetic skill node
 */

/** Strip UTF-8 BOM if present. */
function stripBom(content: string): string {
  return content.charCodeAt(0) === 0xfeff ? content.slice(1) : content;
}

/** Remove content inside fenced code blocks (``` or ~~~). */
function stripFencedCodeBlocks(content: string): string {
  return content.replace(/^(`{3,}|~{3,})[^\n]*\n[\s\S]*?^\1\s*$/gm, '');
}

/** Check if content has @identity at start of line (outside fenced blocks). */
function hasPrsIdentityBlock(content: string): boolean {
  const stripped = stripFencedCodeBlocks(content);
  return /^@identity\b/m.test(stripped);
}

/** Check if content starts with YAML frontmatter. */
function hasYamlFrontmatter(content: string): boolean {
  const trimmed = content.trimStart();
  return trimmed.startsWith('---\n') || trimmed.startsWith('---\r\n');
}

export type ContentType = 'prs' | 'skill' | 'raw';

/**
 * Detect the content type of a .md file.
 *
 * Precedence: PRS (@identity) > skill (frontmatter) > raw
 */
export function detectContentType(content: string): ContentType {
  const clean = stripBom(content);

  if (hasPrsIdentityBlock(clean)) {
    return 'prs';
  }

  if (hasYamlFrontmatter(clean)) {
    return 'skill';
  }

  return 'raw';
}

export { detectContentType, type ContentType } from './content-detector.js';

describe('.md extension handling', () => {
  it('should NOT append .prs when path ends with .md (resolveRef)', () => {
    const ref = createPathRef('./skills/my-skill.md', { isRelative: true });
    const result = loader.resolveRef(ref, '/project/main.prs');
    expect(result).toMatch(/my-skill\.md$/);
    expect(result).not.toMatch(/\.prs$/);
  });

  it('should NOT append .prs when path ends with .md (toAbsolutePath registry)', () => {
    const result = loader.toAbsolutePath('@org/skills/my-skill.md');
    expect(result).toMatch(/my-skill\.md$/);
    expect(result).not.toMatch(/\.prs$/);
  });

  it('should still append .prs for paths without .md extension', () => {
    const ref = createPathRef('./skills/my-skill', { isRelative: true });
    const result = loader.resolveRef(ref, '/project/main.prs');
    expect(result).toMatch(/my-skill\.prs$/);
  });
});

if (ref.isRelative) {
  const dir = dirname(fromFile);
  const rawPath = ref.raw.endsWith('.prs') || ref.raw.endsWith('.md') ? ref.raw : `${ref.raw}.prs`;
  return resolve(dir, rawPath);
}

const fileName =
  segments.endsWith('.prs') || segments.endsWith('.md') ? segments : `${segments}.prs`;

const fileName = path.endsWith('.prs') || path.endsWith('.md') ? path : `${path}.prs`;

import { describe, it, expect } from 'vitest';
import { resolve } from 'path';
import { Resolver } from '../resolver.js';
import { FileLoader } from '../loader.js';

const FIXTURES = resolve(__dirname, '__fixtures__/md-imports');

describe('.md imports', () => {
  it('should resolve @use with .md skill (frontmatter)', async () => {
    const resolver = new Resolver({ registryPath: FIXTURES, localPath: FIXTURES });
    const result = await resolver.resolve(resolve(FIXTURES, 'main.prs'));

    expect(result.errors).toHaveLength(0);
    expect(result.ast).not.toBeNull();

    const skillsBlock = result.ast!.blocks.find((b) => b.name === 'skills');
    expect(skillsBlock).toBeDefined();

    const content = skillsBlock!.content as ObjectContent;
    expect(content.properties['test-skill']).toBeDefined();
  });
});

import { basename } from 'path';

/** Derive skill name from file path (e.g., '/path/to/my-skill.md' → 'my-skill'). */
export function skillNameFromPath(filePath: string): string {
  return basename(filePath, '.md');
}

private async loadAndParse(
  absPath: string,
  sources: string[],
  errors: ResolveError[]
): Promise<{ ast: Program | null }> {
  let source: string;
  try {
    source = await this.loader.load(absPath);
  } catch (err) {
    if (err instanceof FileNotFoundError) {
      // Directory fallback: strip .prs, check if it's a directory
      if (absPath.endsWith('.prs')) {
        const dirPath = absPath.slice(0, -4);
        const dirResult = await this.tryDirectoryScan(dirPath, sources, errors);
        if (dirResult) return dirResult;
      }
      errors.push(new ResolveError(err.message));
      return { ast: null };
    }
    throw err;
  }

  // .md file intercept
  if (absPath.endsWith('.md')) {
    return this.loadAndParseMd(absPath, source, sources, errors);
  }

  const parseResult = parse(source, { filename: absPath });
  // ... rest unchanged
}

import { detectContentType } from './content-detector.js';
import { parseSkillMd, skillNameFromPath } from './skills.js';
import { makeBlock, makeObjectContent, makeTextContent, VIRTUAL_LOC } from './ast-factory.js';

private async loadAndParseMd(
  absPath: string,
  source: string,
  sources: string[],
  errors: ResolveError[]
): Promise<{ ast: Program | null }> {
  const contentType = detectContentType(source);

  if (contentType === 'prs') {
    // Parse as PromptScript
    const parseResult = parse(source, { filename: absPath });
    if (!parseResult.ast) {
      for (const e of parseResult.errors) {
        errors.push(new ResolveError(e.message, e.location));
      }
      return { ast: null };
    }
    return { ast: parseResult.ast };
  }

  // Skill or raw markdown → synthesize Program
  const parsed = parseSkillMd(source);
  const skillName = parsed.name ?? skillNameFromPath(absPath);

  if (!parsed.name) {
    this.logger.warn(`Missing frontmatter in ${absPath} — using filename "${skillName}" as skill name`);
  }

  const skillProps: Record<string, Value> = {};
  if (parsed.description) {
    skillProps['description'] = parsed.description;
  }
  if (parsed.content) {
    skillProps['content'] = makeTextContent(parsed.content, absPath);
  }

  const program: Program = {
    type: 'Program',
    blocks: [makeBlock('skills', makeObjectContent({ [skillName]: skillProps }))],
    uses: [],
    extends: [],
    loc: VIRTUAL_LOC,
  };

  return { ast: program };
}

it('should resolve directory import scanning for skills', async () => {
  const loader = new FileLoader(FIXTURES, FIXTURES);
  const resolver = new Resolver(loader, { logger: silentLogger });
  const result = await resolver.resolve(resolve(FIXTURES, 'main-dir.prs'));

  expect(result.errors).toHaveLength(0);
  const skillsBlock = result.ast!.blocks.find((b) => b.name === 'skills');
  expect(skillsBlock).toBeDefined();

  const content = skillsBlock!.content as ObjectContent;
  expect(content.properties['alpha']).toBeDefined();
  expect(content.properties['beta']).toBeDefined();
});

import { lstat, readdir, readFile } from 'fs/promises';

private async tryDirectoryScan(
  dirPath: string,
  sources: string[],
  errors: ResolveError[]
): Promise<{ ast: Program | null } | null> {
  try {
    const stat = await lstat(dirPath);
    if (!stat.isDirectory()) return null;
  } catch {
    return null;
  }

  this.logger.debug(`Scanning directory for skills: ${dirPath}`);
  const skillProperties = await this.scanDirectoryForSkills(dirPath);

  if (!skillProperties || Object.keys(skillProperties).length === 0) {
    errors.push(new ResolveError(`No skills found in directory: ${dirPath}`));
    return { ast: null };
  }

  const program: Program = {
    type: 'Program',
    blocks: [makeBlock('skills', makeObjectContent(skillProperties))],
    uses: [],
    extends: [],
    loc: VIRTUAL_LOC,
  };

  return { ast: program };
}

private async scanDirectoryForSkills(
  dir: string,
  depth = 0
): Promise<Record<string, Value>> {
  if (depth >= 3) return {};

  const properties: Record<string, Value> = {};
  let entries;
  try {
    entries = await readdir(dir, { withFileTypes: true });
  } catch {
    return {};
  }

  for (const entry of entries) {
    if (!entry.isDirectory() || entry.isSymbolicLink()) continue;

    const subdir = resolve(dir, entry.name);

    // Convention 1: SKILL.md
    const skillMdPath = resolve(subdir, 'SKILL.md');
    // Convention 2: <dirname>.md
    const dirnameMdPath = resolve(subdir, `${entry.name}.md`);

    let mdPath: string | null = null;
    try {
      await lstat(skillMdPath);
      mdPath = skillMdPath;
    } catch {
      try {
        await lstat(dirnameMdPath);
        mdPath = dirnameMdPath;
      } catch {
        // Recurse deeper
        const nested = await this.scanDirectoryForSkills(subdir, depth + 1);
        Object.assign(properties, nested);
        continue;
      }
    }

    if (mdPath) {
      try {
        const raw = await readFile(mdPath, 'utf-8');
        const parsed = parseSkillMd(raw);
        const skillName = parsed.name ?? entry.name;

        const skillProps: Record<string, Value> = {};
        if (parsed.description) skillProps['description'] = parsed.description;
        if (parsed.content) {
          skillProps['content'] = makeTextContent(parsed.content, mdPath);
        }
        properties[skillName] = skillProps;
      } catch {
        // Skip unreadable skill files
      }
    }
  }

  return properties;
}

it('should NOT append .prs when path ends with .md', () => {
  const result = registry['resolveFilePath']('/repo', 'skills/my-skill.md');
  expect(result).toMatch(/my-skill\.md$/);
  expect(result).not.toMatch(/\.prs$/);
});

private resolveFilePath(repoPath: string, relativePath: string): string {
  let cleanPath = relativePath;

  // Add .prs extension if not present, not .md, and not ending with /
  if (!cleanPath.endsWith('.prs') && !cleanPath.endsWith('.md') && !cleanPath.endsWith('/')) {
    cleanPath += '.prs';
  }

  if (this.subPath) {
    return join(repoPath, this.subPath, cleanPath);
  }
  return join(repoPath, cleanPath);
}

// Resolve the file path within the cached repo
const isMdPath = subPath.endsWith('.md');
const prsFileName = isMdPath ? subPath : subPath.endsWith('.prs') ? subPath : `${subPath}.prs`;
const fullPath = join(cachePath, prsFileName);

let resolvedAST: Program | null = null;

if (existsSync(fullPath)) {
  if (isMdPath) {
    // .md file — use content detection
    const source = await this.loader.load(fullPath);
    const loadResult = await this.loadAndParseMd(fullPath, source, sources, errors);
    resolvedAST = loadResult.ast;
  } else {
    // .prs file — parse normally
    const source = await this.loader.load(fullPath);
    const parseResult = parse(source, { filename: fullPath });
    if (parseResult.ast) {
      resolvedAST = parseResult.ast;
    } else {
      for (const e of parseResult.errors) {
        errors.push(new ResolveError(e.message, e.location));
      }
    }
  }
} else {
  // Directory or auto-discovery fallback
  const discoverDir = join(cachePath, subPath);
  // Try directory scan first
  const dirResult = await this.tryDirectoryScan(discoverDir, sources, errors);
  if (dirResult?.ast) {
    resolvedAST = dirResult.ast;
  } else {
    // Fall back to auto-discovery
    resolvedAST = await discoverNativeContent(discoverDir);
    if (!resolvedAST) {
      errors.push(
        new ResolveError(
          `Cannot resolve registry import: no .prs file, .md file, or native content at '${subPath}' in ${repoUrl}`
        )
      );
    }
  }
}

// Before:
const parsed = parseYaml(raw);
// After:
const parsed = parseYaml(raw, { maxAliasCount: 100 });

// Preserve .md-sourced entries from previous lock
const mdEntries: Record<string, LockfileDependency> = {};
if (existingLock) {
  for (const [key, dep] of Object.entries(existingLock.dependencies)) {
    if (dep.source === 'md') {
      mdEntries[key] = dep;
    }
  }
}

// After generating new dependencies, merge:
const allDeps = { ...newDeps, ...mdEntries };

it('should reject path traversal outside project root', () => {
  const ref = createPathRef('./../../etc/passwd', { isRelative: true });
  expect(() => loader.resolveRef(ref, '/project/main.prs')).toThrow(/path traversal/i);
});

if (ref.isRelative) {
  const dir = dirname(fromFile);
  const rawPath = ref.raw.endsWith('.prs') || ref.raw.endsWith('.md') ? ref.raw : `${ref.raw}.prs`;
  const resolved = resolve(dir, rawPath);

  // Path traversal check
  const projectRoot = this.localPath;
  if (!resolved.startsWith(projectRoot)) {
    throw new PSError(`Path traversal outside project root is not allowed: ${ref.raw}`);
  }

  return resolved;
}