gipity 1.0.355 → 1.0.365

package/dist/commands/page-test.js

@@ -0,0 +1,86 @@
+import { Command } from 'commander';
+import { post } from '../api.js';
+import { brand, bold, muted, warning, success, error as clrError } from '../colors.js';
+import { run } from '../helpers/index.js';
+// Lines worth surfacing - genuine errors and crash signatures, not benign warnings.
+const BAD = /^error:|uncaught|unhandled|message handler error|\bcrash|RuntimeError/i;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Run one passive page load via the inspect endpoint and return its console. */
+async function inspectClient(url, waitMs, i) {
+    try {
+        const res = await post('/tools/browser/inspect', { url, waitMs });
+        return { i, lines: res.data.console ?? [] };
+    }
+    catch (err) {
+        return { i, lines: [], error: err instanceof Error ? err.message : String(err) };
+    }
+}
+// Headless multi-client realtime check: spin N staggered browser clients at a
+// deployed URL and flag error/crash lines across their consoles. The verifier
+// for realtime apps (host election, presence, world sync, reconnection) -
+// promotes the internal multi-client-test script to a first-class command.
+//
+// Passive page loads only: each client just loads the URL and settles. An app
+// that connects to realtime only after a user action (e.g. a lobby that joins
+// on a button press) needs a URL-param test mode so the load alone exercises
+// the path - see the app-realtime skill.
+export const pageTestCommand = new Command('test')
+    .description('Multi-client realtime check: load a URL in N staggered headless clients, flag console errors')
+    .argument('<url>', 'Deployed URL to load in every client')
+    .option('--clients <n>', 'Number of headless clients to launch', '2')
+    .option('--stagger <s>', 'Seconds between client starts (client 0 settles first, e.g. as host)', '12')
+    .option('--wait <ms>', 'Milliseconds each client stays open after load (max 30000)', '24000')
+    .option('--json', 'Output as JSON')
+    .action((url, opts) => run('Page test', async () => {
+    const clients = Math.max(1, parseInt(opts.clients, 10) || 2);
+    const stagger = Math.max(0, parseInt(opts.stagger, 10) || 0);
+    const wait = Math.min(30000, Math.max(2000, parseInt(opts.wait, 10) || 24000));
+    if (!opts.json) {
+        console.log(`\n${brand('Page test')} ${bold(url)}`);
+        console.log(`  ${muted(`${clients} client(s), stagger ${stagger}s, ${wait}ms open each`)}\n`);
+    }
+    const runs = [];
+    for (let i = 0; i < clients; i++) {
+        runs.push((async () => {
+            await sleep(i * stagger * 1000);
+            if (!opts.json)
+                console.log(`  ${muted(`client ${i}${i === 0 ? ' (first)' : ''} starting`)}`);
+            return inspectClient(url, wait, i);
+        })());
+    }
+    const results = (await Promise.all(runs)).sort((a, b) => a.i - b.i);
+    let problems = 0;
+    for (const r of results) {
+        if (r.error)
+            problems++;
+        else
+            problems += r.lines.filter((l) => BAD.test(l)).length;
+    }
+    if (opts.json) {
+        console.log(JSON.stringify({ url, clients, stagger, wait, problems, results }));
+        if (problems > 0)
+            process.exitCode = 1;
+        return;
+    }
+    for (const r of results) {
+        console.log(`\n${bold(`=== client ${r.i}${r.i === 0 ? ' (first)' : ''} ===`)}`);
+        if (r.error) {
+            console.log(`  ${clrError(`page inspect failed: ${r.error}`)}`);
+            continue;
+        }
+        if (r.lines.length === 0) {
+            console.log(`  ${muted('(no console output)')}`);
+            continue;
+        }
+        for (const line of r.lines) {
+            const bad = BAD.test(line);
+            console.log(`  ${bad ? warning('⚠ ' + line) : ' ' + line}`);
+        }
+    }
+    console.log(problems === 0
+        ? `\n${success('✓ no error/crash lines across all clients')}\n`
+        : `\n${clrError(`⚠ ${problems} error/crash line(s) flagged above`)}\n`);
+    if (problems > 0)
+        process.exitCode = 1;
+}));
+//# sourceMappingURL=page-test.js.map

package/dist/commands/page.js

@@ -2,15 +2,17 @@ import { Command } from 'commander';
 import { pageInspectCommand } from './page-inspect.js';
 import { pageScreenshotCommand } from './page-screenshot.js';
 import { pageEvalCommand } from './page-eval.js';
+import { pageTestCommand } from './page-test.js';
 // Parent namespace grouping the page/browser diagnostics under one command:
-//   gipity page inspect | eval | screenshot
+//   gipity page inspect | eval | screenshot | test
 // Each subcommand is canonical for its capability; the namespace keeps the
 // top-level surface lean and makes the siblings discoverable via `page --help`.
 export const pageCommand = new Command('page')
-    .description('Inspect, evaluate, and screenshot web pages (page inspect | eval | screenshot)')
+    .description('Inspect, evaluate, screenshot, and multi-client test web pages (page inspect | eval | screenshot | test)')
     .addCommand(pageInspectCommand)
     .addCommand(pageEvalCommand)
-    .addCommand(pageScreenshotCommand);
+    .addCommand(pageScreenshotCommand)
+    .addCommand(pageTestCommand);
 // No subcommand → show help instead of commander's terse error.
 pageCommand.action(() => {
     pageCommand.help();

package/dist/commands/service.js

@@ -0,0 +1,56 @@
+import { Command } from 'commander';
+import { get, post } from '../api.js';
+import { requireConfig } from '../config.js';
+import { bold, muted } from '../colors.js';
+import { run } from '../helpers/index.js';
+/** Known app-service endpoints, shown by `gipity service list` and used to
+ *  give a helpful hint on typos. POST endpoints take a JSON body; GET
+ *  endpoints (model/voice listings) are reached with `--get`. */
+const SERVICES = [
+    { name: 'llm', method: 'POST', desc: 'Chat completion ({ prompt | messages, model?, ... })' },
+    { name: 'llm/models', method: 'GET', desc: 'List available LLM models' },
+    { name: 'image', method: 'POST', desc: 'Generate an image ({ prompt, provider?, size? })' },
+    { name: 'image/models', method: 'GET', desc: 'List image providers/models' },
+    { name: 'tts', method: 'POST', desc: 'Text-to-speech ({ text, voice?, ... })' },
+    { name: 'tts/voices', method: 'GET', desc: 'List TTS voices' },
+    { name: 'sound', method: 'POST', desc: 'Sound effect ({ prompt, duration_seconds? })' },
+    { name: 'music', method: 'POST', desc: 'Music generation ({ prompt, duration_seconds? })' },
+    { name: 'video', method: 'POST', desc: 'Video generation ({ prompt, ... })' },
+    { name: 'location/ip', method: 'POST', desc: 'IP geolocation ({ ip? })' },
+    { name: 'location/geocode', method: 'POST', desc: 'Reverse geocode ({ lat, lon })' },
+];
+export const serviceCommand = new Command('service')
+    .description('Call a Gipity app service (LLM, image, music, TTS, ...)');
+serviceCommand
+    .command('list')
+    .description('List callable app services')
+    .action(() => run('Services', async () => {
+    requireConfig();
+    const width = SERVICES.reduce((m, s) => Math.max(m, s.name.length), 0);
+    console.log('');
+    console.log('Call one with `gipity service call <name> \'{"json":"body"}\'`');
+    console.log(muted('(GET endpoints like llm/models, tts/voices take --get and no body)'));
+    console.log('');
+    for (const s of SERVICES) {
+        console.log(`  ${bold(s.name.padEnd(width))}  ${muted(`[${s.method}] ${s.desc}`)}`);
+    }
+    console.log('');
+}));
+serviceCommand
+    .command('call <name> [body]')
+    .description('Call an app service by name (e.g. llm, image, music). Uses your logged-in session - no token wrangling.')
+    .option('--data <json>', 'JSON request body (alternative to the positional [body])')
+    .option('--get', 'Issue a GET (for listing endpoints like llm/models, tts/voices)')
+    .option('--json', 'Output compact JSON')
+    .action((name, bodyArg, opts) => run('Call', async () => {
+    const config = requireConfig();
+    // Encode each path segment but preserve the `/` separators so subpaths
+    // like `location/geocode` and `llm/models` resolve correctly.
+    const path = name.split('/').map(encodeURIComponent).join('/');
+    const url = `/api/${config.projectGuid}/services/${path}`;
+    const res = opts.get
+        ? await get(url)
+        : await post(url, JSON.parse(bodyArg || opts.data || '{}'));
+    console.log(opts.json ? JSON.stringify(res) : JSON.stringify(res, null, 2));
+}));
+//# sourceMappingURL=service.js.map

package/dist/commands/skill.js

@@ -16,7 +16,8 @@ skillCommand
         process.exit(1);
     }
     const res = await get(`/skills?agent=${config.agentGuid}`);
-    printList(res.data, opts, 'No skills available.', s => `${bold(s.name)}  ${muted(s.description)}`);
+    const width = res.data.reduce((m, s) => Math.max(m, s.name.length), 0);
+    printList(res.data, opts, 'No skills available.', s => `  ${bold(s.name.padEnd(width))}  ${muted(s.description)}`, 'Read one with `gipity skill read <name>`:');
 }));
 skillCommand
     .command('read <name>')

package/dist/commands/text.js

@@ -0,0 +1,148 @@
+import { Command } from 'commander';
+import { readFileSync } from 'fs';
+import { run } from '../helpers/command.js';
+import { error as clrError, bold, dim, brand } from '../colors.js';
+import { analyzeText, countOccurrences, findPositions, nthWord, nthChar, areAnagrams, } from '../helpers/text-analysis.js';
+/** Read text from --file, a positional arg, or stdin (in that precedence). */
+function resolveInput(args, opts) {
+    if (opts.file)
+        return readFileSync(opts.file, 'utf-8');
+    if (args.length)
+        return args.join(' ');
+    // No arg → read stdin (supports `echo … | gipity text analyze`).
+    try {
+        return readFileSync(0, 'utf-8');
+    }
+    catch {
+        return '';
+    }
+}
+function formatProfile(a) {
+    const L = [];
+    const row = (label, val) => L.push(`  ${label.padEnd(22)}${val}`);
+    L.push(bold('Counts'));
+    row('Characters', a.characters);
+    row('Chars (no spaces)', a.charactersNoSpaces);
+    row('Chars (no whitespace)', a.charactersNoWhitespace);
+    row('Letters', a.letters);
+    row('  Uppercase', a.uppercase);
+    row('  Lowercase', a.lowercase);
+    row('  Vowels (a-z)', a.vowels);
+    row('  Consonants (a-z)', a.consonants);
+    row('Digits', a.digits);
+    row('Punctuation/symbols', a.punctuation);
+    row('Whitespace', a.whitespace);
+    row('Spaces', a.spaces);
+    if (a.other)
+        row('Other', a.other);
+    L.push('');
+    L.push(bold('Words & structure'));
+    row('Words', a.words);
+    row('Unique words', a.uniqueWords);
+    row('Sentences', a.sentences);
+    row('Lines', a.lines);
+    row('Paragraphs', a.paragraphs);
+    if (a.words) {
+        row('Longest word', `${a.longestWord} (${[...a.longestWord].length})`);
+        row('Shortest word', `${a.shortestWord} (${[...a.shortestWord].length})`);
+        row('Avg word length', a.averageWordLength);
+    }
+    L.push('');
+    L.push(bold('Letter frequency') + dim('  (a–z, case-insensitive)'));
+    if (a.letterFrequency.length) {
+        const freq = a.letterFrequency
+            .map((f) => `${f.letter}:${f.count}`)
+            .join('  ');
+        L.push(`  ${freq}`);
+    }
+    else {
+        L.push(dim('  (no letters)'));
+    }
+    if (a.wordFrequency.length) {
+        L.push('');
+        L.push(bold('Top words'));
+        L.push('  ' + a.wordFrequency.map((w) => `${w.word}:${w.count}`).join('  '));
+    }
+    L.push('');
+    L.push(bold('Other'));
+    row('Reversed', a.reversed);
+    row('Palindrome', a.isPalindrome ? 'yes' : 'no');
+    return L.join('\n');
+}
+const analyzeCommand = new Command('analyze')
+    .description('Deterministic character/word analysis of text (local, no network)')
+    .argument('[text...]', 'Text to analyze (or pipe via stdin, or use --file)')
+    .option('--file <path>', 'Read text from a file')
+    .option('--count <substring>', 'Count occurrences of a substring')
+    .option('--find <substring>', 'List 1-indexed positions of a substring')
+    .option('--word <n>', 'Return the Nth word (negative counts from the end)', (v) => parseInt(v, 10))
+    .option('--char <n>', 'Return the Nth character (negative counts from the end)', (v) => parseInt(v, 10))
+    .option('--anagram <other>', 'Check whether the text is an anagram of <other>')
+    .option('--whole-word', 'Match whole words only (for --count)')
+    .option('--case-sensitive', 'Make --count / --find case-sensitive')
+    .option('--json', 'Output as JSON')
+    .action((args, opts) => run('Text analyze', async () => {
+    const text = resolveInput(args, opts);
+    if (text === '' && !opts.file) {
+        console.error(clrError('No text. Pass it as an argument, pipe via stdin, or use --file.'));
+        process.exit(1);
+    }
+    // Targeted queries short-circuit the full profile.
+    if (opts.count !== undefined) {
+        const r = countOccurrences(text, opts.count, !!opts.caseSensitive, !!opts.wholeWord);
+        if (opts.json)
+            return void console.log(JSON.stringify(r));
+        const mode = [
+            r.caseSensitive ? 'case-sensitive' : 'case-insensitive',
+            r.wholeWord ? 'whole-word' : null,
+        ].filter(Boolean).join(', ');
+        const counts = r.wholeWord
+            ? `${r.nonOverlapping}`
+            : `${r.nonOverlapping} non-overlapping, ${r.overlapping} overlapping`;
+        console.log(`  "${r.needle}" (${mode}): ${counts}`);
+        return;
+    }
+    if (opts.find !== undefined) {
+        const positions = findPositions(text, opts.find, !!opts.caseSensitive);
+        if (opts.json)
+            return void console.log(JSON.stringify({ needle: opts.find, positions }));
+        console.log(positions.length
+            ? `  "${opts.find}" at: ${positions.join(', ')}`
+            : dim(`  "${opts.find}" not found`));
+        return;
+    }
+    if (opts.anagram !== undefined) {
+        const r = areAnagrams(text, opts.anagram);
+        if (opts.json)
+            return void console.log(JSON.stringify(r));
+        console.log(`  ${r.isAnagram ? 'yes' : 'no'} - anagram of "${opts.anagram}"`);
+        return;
+    }
+    if (opts.word !== undefined) {
+        const w = nthWord(text, opts.word);
+        if (opts.json)
+            return void console.log(JSON.stringify({ word: w, n: opts.word }));
+        console.log(w === null ? dim('  (out of range)') : `  ${w}`);
+        return;
+    }
+    if (opts.char !== undefined) {
+        const c = nthChar(text, opts.char);
+        if (opts.json)
+            return void console.log(JSON.stringify({ char: c, n: opts.char }));
+        console.log(c === null ? dim('  (out of range)') : `  ${c}`);
+        return;
+    }
+    const analysis = analyzeText(text);
+    if (opts.json)
+        return void console.log(JSON.stringify(analysis));
+    console.log(formatProfile(analysis));
+}));
+// Parent namespace. One capability today (analyze); namespaced for a lean
+// top-level surface and room for future text operations.
+export const textCommand = new Command('text')
+    .description(`Deterministic text analysis - char/word counts, frequency, occurrences (${brand('text analyze')})`)
+    .addCommand(analyzeCommand);
+textCommand.action(() => {
+    textCommand.help();
+});
+//# sourceMappingURL=text.js.map

package/dist/commands/workflow.js

@@ -158,24 +158,20 @@ workflowCommand
     printResult(`Deleted "${wf.name}".`, opts, { deleted: wf.name, short_guid: wf.short_guid });
 }));
 // Resolve a workflow by name within the linked project (like `gipity fn`), or
-// by short_guid anywhere. Names are unique per active project workflow (DB
-// constraint), so a bare name in this project is unambiguous; the same name in
-// another project is a different workflow and simply isn't matched here.
+// by short_guid anywhere. Uses the single account-wide `/workflows` list (the
+// same endpoint the bare `workflow` list hits) so the whole command stays on
+// one route tree. Names are unique per active project workflow (DB constraint),
+// so we scope by the current project's slug; a short_guid resolves anywhere.
 async function resolveWorkflow(name) {
-    const { projectGuid } = requireConfig();
-    const res = await get(`/projects/${projectGuid}/workflows`);
-    const list = res.data ?? [];
-    // Exact short_guid match wins — unambiguous override.
-    const byGuid = list.find(w => w.short_guid === name);
+    const { projectSlug } = requireConfig();
+    const res = await get('/workflows');
+    const all = res.data ?? [];
+    // Exact short_guid match wins anywhere — unambiguous override.
+    const byGuid = all.find(w => w.short_guid === name);
     if (byGuid)
         return byGuid;
-    const byName = list.filter(w => w.name === name);
+    const byName = all.filter(w => w.project_slug === projectSlug && w.name === name);
     if (byName.length === 0) {
-        // Fall back to a global short_guid lookup (e.g. account-level workflows).
-        const all = await get('/workflows');
-        const global = (all.data ?? []).find(w => w.short_guid === name);
-        if (global)
-            return global;
         console.error(clrError(`Workflow "${name}" not found in this project.`));
         process.exit(1);
     }

package/dist/config.js

@@ -1,5 +1,5 @@
 import { readFileSync, writeFileSync, existsSync } from 'fs';
-import { resolve } from 'path';
+import { dirname, resolve } from 'path';
 const CONFIG_FILE = '.gipity.json';
 let cached = null;
 let cachedPath = null;
@@ -30,6 +30,13 @@ export function getConfigPath() {
     cachedPath = findConfigPath();
     return cachedPath;
 }
+/** Directory holding the project's `.gipity.json` (the project root), found by
+ *  walking up from cwd. Returns null when there's no linked project in the tree
+ *  (e.g. one-off mode), in which case callers should anchor to cwd. */
+export function getProjectRoot() {
+    const path = getConfigPath();
+    return path ? dirname(path) : null;
+}
 export function getConfig() {
     if (cached)
         return cached;

package/dist/help-skills.js

@@ -5,6 +5,7 @@ import { muted } from './colors.js';
 export const HELP_SKILL_MAP = {
     fn: 'app-development',
     db: 'app-development',
+    text: 'text-analysis',
 };
 /**
  * Fetch a skill by name from the server and print its content.

package/dist/helpers/output.js

@@ -28,7 +28,7 @@ export function printResult(text, opts, jsonData) {
  * Print a list with JSON mode, empty state, and per-item formatting.
  * Replaces the most common output pattern across all commands.
  */
-export function printList(data, opts, emptyMsg, formatter) {
+export function printList(data, opts, emptyMsg, formatter, header) {
     if (opts.json) {
         console.log(JSON.stringify(data));
         return;
@@ -38,6 +38,12 @@ export function printList(data, opts, emptyMsg, formatter) {
         console.log(emptyMsg);
     }
     else {
+        // A `header` is a one-line lead-in (e.g. "Read one with `gipity skill
+        // read <name>`:") that tells the reader what the listed names are for.
+        if (header) {
+            console.log(header);
+            console.log('');
+        }
         for (const item of data) {
             console.log(formatter(item));
         }

package/dist/helpers/text-analysis.js

@@ -0,0 +1,200 @@
+/**
+ * text-analysis.ts - Pure, deterministic text analysis.
+ *
+ * MIRRORED from platform/packages/shared/src/text-analysis.ts. The CLI ships
+ * standalone (it does not depend on @easyclaw/shared), so this is a hand copy
+ * of the canonical logic - same pattern as the TEMPLATES/KITS catalog mirror
+ * in add.ts / prompts.ts. The drift guard in cli-cmd-text.test.ts asserts the
+ * body below stays byte-identical to the shared source (the source of truth).
+ *
+ * Everything operates on Unicode code points (via `[...text]`) so multi-byte
+ * characters count as one, and the category counts always sum to the total.
+ */
+/** How many top entries the word-frequency list keeps. */
+export const WORD_FREQUENCY_TOP = 10;
+const VOWELS = new Set(['a', 'e', 'i', 'o', 'u']);
+/** Split into Unicode code points (so emoji / accented chars count as one). */
+function chars(text) {
+    return [...text];
+}
+/** Whitespace-separated tokens, empties dropped. */
+function tokenize(text) {
+    return text.split(/\s+/).filter(Boolean);
+}
+/** Strip leading/trailing punctuation/symbols from a token for word identity. */
+function trimWordPunct(token) {
+    return token.replace(/^[\p{P}\p{S}]+|[\p{P}\p{S}]+$/gu, '');
+}
+/** Normalize to lowercase alphanumerics only (for palindrome / anagram). */
+function alnumLower(text) {
+    return chars(text)
+        .filter((ch) => /[\p{L}\p{N}]/u.test(ch))
+        .map((ch) => ch.toLowerCase());
+}
+export function analyzeText(text) {
+    const cps = chars(text);
+    let letters = 0;
+    let uppercase = 0;
+    let lowercase = 0;
+    let vowels = 0;
+    let consonants = 0;
+    let digits = 0;
+    let punctuation = 0;
+    let whitespace = 0;
+    let spaces = 0;
+    let other = 0;
+    const freq = new Map();
+    for (const ch of cps) {
+        if (/\s/u.test(ch)) {
+            whitespace++;
+            if (ch === ' ')
+                spaces++;
+        }
+        else if (/\p{L}/u.test(ch)) {
+            letters++;
+            if (/\p{Lu}/u.test(ch))
+                uppercase++;
+            else if (/\p{Ll}/u.test(ch))
+                lowercase++;
+            if (/[a-z]/i.test(ch)) {
+                const lower = ch.toLowerCase();
+                freq.set(lower, (freq.get(lower) ?? 0) + 1);
+                if (VOWELS.has(lower))
+                    vowels++;
+                else
+                    consonants++;
+            }
+        }
+        else if (/\p{Nd}/u.test(ch)) {
+            digits++;
+        }
+        else if (/[\p{P}\p{S}]/u.test(ch)) {
+            punctuation++;
+        }
+        else {
+            other++;
+        }
+    }
+    const tokens = tokenize(text);
+    const lengths = tokens.map((t) => chars(t).length);
+    const cleaned = tokens.map((t) => trimWordPunct(t).toLowerCase()).filter(Boolean);
+    const uniq = new Set(cleaned);
+    const wordFreqMap = new Map();
+    for (const w of cleaned)
+        wordFreqMap.set(w, (wordFreqMap.get(w) ?? 0) + 1);
+    const wordFrequency = [...wordFreqMap.entries()]
+        .map(([word, count]) => ({ word, count }))
+        .sort((a, b) => b.count - a.count || a.word.localeCompare(b.word))
+        .slice(0, WORD_FREQUENCY_TOP);
+    const sentences = (text.match(/[.!?]+(?=\s|$)/gu) ?? []).length;
+    const lines = text === '' ? 0 : text.split('\n').length;
+    const paragraphs = text.split(/\n\s*\n/).map((p) => p.trim()).filter(Boolean).length;
+    const longestWord = tokens.reduce((a, b) => (chars(b).length > chars(a).length ? b : a), '');
+    const shortestWord = tokens.length
+        ? tokens.reduce((a, b) => (chars(b).length < chars(a).length ? b : a))
+        : '';
+    const averageWordLength = lengths.length
+        ? Math.round((lengths.reduce((a, b) => a + b, 0) / lengths.length) * 10) / 10
+        : 0;
+    const letterFrequency = [...freq.entries()]
+        .map(([letter, count]) => ({ letter, count }))
+        .sort((a, b) => b.count - a.count || a.letter.localeCompare(b.letter));
+    const reversed = cps.slice().reverse().join('');
+    const normalized = alnumLower(text);
+    const isPalindrome = normalized.length > 0 &&
+        normalized.join('') === normalized.slice().reverse().join('');
+    return {
+        characters: cps.length,
+        charactersNoSpaces: cps.length - spaces,
+        charactersNoWhitespace: cps.length - whitespace,
+        letters,
+        uppercase,
+        lowercase,
+        vowels,
+        consonants,
+        digits,
+        punctuation,
+        whitespace,
+        spaces,
+        other,
+        words: tokens.length,
+        uniqueWords: uniq.size,
+        sentences,
+        lines,
+        paragraphs,
+        longestWord,
+        shortestWord,
+        averageWordLength,
+        letterFrequency,
+        wordFrequency,
+        reversed,
+        isPalindrome,
+    };
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Count occurrences of a substring.
+ * - Default: both overlapping and non-overlapping counts (they differ for
+ *   self-overlapping needles like "aa").
+ * - wholeWord: count only whole-word matches (\b boundaries); overlapping and
+ *   non-overlapping are equal in that mode.
+ */
+export function countOccurrences(text, needle, caseSensitive = false, wholeWord = false) {
+    if (needle === '') {
+        return { needle, caseSensitive, wholeWord, overlapping: 0, nonOverlapping: 0 };
+    }
+    if (wholeWord) {
+        const flags = caseSensitive ? 'gu' : 'giu';
+        const re = new RegExp(`\\b${escapeRegExp(needle)}\\b`, flags);
+        const n = (text.match(re) ?? []).length;
+        return { needle, caseSensitive, wholeWord, overlapping: n, nonOverlapping: n };
+    }
+    const hay = caseSensitive ? text : text.toLowerCase();
+    const sub = caseSensitive ? needle : needle.toLowerCase();
+    let overlapping = 0;
+    for (let i = hay.indexOf(sub); i !== -1; i = hay.indexOf(sub, i + 1))
+        overlapping++;
+    let nonOverlapping = 0;
+    for (let i = hay.indexOf(sub); i !== -1; i = hay.indexOf(sub, i + sub.length))
+        nonOverlapping++;
+    return { needle, caseSensitive, wholeWord, overlapping, nonOverlapping };
+}
+/** 1-indexed code-point positions where a substring starts (overlapping). */
+export function findPositions(text, needle, caseSensitive = false) {
+    if (needle === '')
+        return [];
+    const hay = caseSensitive ? text : text.toLowerCase();
+    const sub = caseSensitive ? needle : needle.toLowerCase();
+    const positions = [];
+    for (let i = hay.indexOf(sub); i !== -1; i = hay.indexOf(sub, i + 1)) {
+        // Convert UTF-16 index to 1-indexed code-point position.
+        positions.push([...hay.slice(0, i)].length + 1);
+    }
+    return positions;
+}
+/** Resolve a 1-indexed position, supporting negatives (-1 = last). */
+function resolveIndex(n, len) {
+    const idx = n < 0 ? len + n + 1 : n;
+    return idx >= 1 && idx <= len ? idx : null;
+}
+/** Nth word (whitespace-separated), 1-indexed; negative counts from the end. */
+export function nthWord(text, n) {
+    const tokens = tokenize(text);
+    const idx = resolveIndex(n, tokens.length);
+    return idx === null ? null : tokens[idx - 1];
+}
+/** Nth character (code point), 1-indexed; negative counts from the end. */
+export function nthChar(text, n) {
+    const cps = chars(text);
+    const idx = resolveIndex(n, cps.length);
+    return idx === null ? null : cps[idx - 1];
+}
+/** Are two strings anagrams? Ignores case, spaces, and punctuation. */
+export function areAnagrams(a, b) {
+    const na = alnumLower(a).sort().join('');
+    const nb = alnumLower(b).sort().join('');
+    return { isAnagram: na.length > 0 && na === nb, normalizedA: na, normalizedB: nb };
+}
+//# sourceMappingURL=text-analysis.js.map