pict-section-prompteditor 1.0.0

package/source/templates/Pict-Template-WordListEntry.js

@@ -0,0 +1,140 @@
+'use strict';
+
+const libPictTemplate = require('pict-template');
+
+/**
+ * The {~WordListEntry:Name~} template expression (short form {~WLE:Name~}).
+ *
+ * Resolves to one entry drawn from the named word list by weighted random:
+ * an entry's chance is weight / sum(weights). With Dinosaurs holding
+ * [["Tyrannosaurus", 3], ["Diplodocus", 1]], the expression renders
+ * Tyrannosaurus 75% of the time and Diplodocus 25%.
+ *
+ * Word lists are found two ways, in order:
+ *
+ *   1. The data record: a generation run passes the lists in the parse data as
+ *      __PromptEditorWordLists ({ lowercased name -> Entries }) along with an
+ *      optional __PromptEditorRandom function. This is what the prompt editor
+ *      view does, and it keeps multiple editor instances exact: each
+ *      generation resolves against precisely the lists it was given.
+ *
+ *   2. The pict-level registry: any prompt editor view (or a host) can push a
+ *      resolver function onto pict.__PictSectionPromptEditorResolvers, so the
+ *      expression also works in ordinary application templates once a section
+ *      is mounted. Resolvers take the lowercased list name and return Entries
+ *      or null.
+ *
+ * A second optional parameter is the default for a miss:
+ * {~WordListEntry:Dinosaurs:a large lizard~} renders the default when the list
+ * does not resolve (or has nothing drawable). The split is on the first colon,
+ * so defaults may contain colons; an empty default ({~WLE:Name:~}) renders
+ * nothing on a miss. With no default, a miss renders the expression back out
+ * literally, so a typo is visible in the generated prompt instead of silently
+ * vanishing. Each occurrence draws independently; two references to the same
+ * list in one prompt can (and should be able to) land on different words.
+ */
+
+/**
+ * Draw one word from [[word, weight], ...] by weighted random. Entries with a
+ * non-positive weight never draw. Returns null for an empty or all-zero list.
+ * @param {Array<Array>} pEntries
+ * @param {function} [pRandom] - returns [0, 1); defaults to Math.random
+ * @returns {string|null}
+ */
+function weightedPick(pEntries, pRandom)
+{
+	if (!Array.isArray(pEntries) || !pEntries.length) { return null; }
+	let tmpRandom = (typeof pRandom === 'function') ? pRandom : Math.random;
+	let tmpTotal = 0;
+	for (let i = 0; i < pEntries.length; i++)
+	{
+		let tmpWeight = Number(pEntries[i][1]);
+		if (isFinite(tmpWeight) && tmpWeight > 0) { tmpTotal += tmpWeight; }
+	}
+	if (tmpTotal <= 0) { return null; }
+	let tmpRoll = tmpRandom() * tmpTotal;
+	for (let i = 0; i < pEntries.length; i++)
+	{
+		let tmpWeight = Number(pEntries[i][1]);
+		if (!isFinite(tmpWeight) || tmpWeight <= 0) { continue; }
+		tmpRoll -= tmpWeight;
+		if (tmpRoll < 0) { return String(pEntries[i][0]); }
+	}
+	// Floating point edge: the roll landed exactly on the total.
+	for (let i = pEntries.length - 1; i >= 0; i--)
+	{
+		if (Number(pEntries[i][1]) > 0) { return String(pEntries[i][0]); }
+	}
+	return null;
+}
+
+class PictTemplateWordListEntry extends libPictTemplate
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
+
+		this.addPattern('{~WordListEntry:', '~}');
+		this.addPattern('{~WLE:', '~}');
+	}
+
+	render(pTemplateHash, pRecord)
+	{
+		let tmpBody = String(pTemplateHash || '').trim();
+		if (!tmpBody) { return ''; }
+
+		// {~WordListEntry:ListName:Default~} -- everything after the FIRST colon
+		// is the default rendered when the list does not resolve (or resolves
+		// with nothing drawable). The default may contain colons, and may be
+		// empty: {~WLE:Name:~} renders nothing on a miss. With no default at
+		// all, a miss echoes the expression so a typo stays findable.
+		let tmpListName = tmpBody;
+		let tmpDefault = null;
+		let tmpColon = tmpBody.indexOf(':');
+		if (tmpColon > -1)
+		{
+			tmpListName = tmpBody.slice(0, tmpColon).trim();
+			tmpDefault = tmpBody.slice(tmpColon + 1).trim();
+		}
+		if (!tmpListName) { return (tmpDefault === null) ? '' : tmpDefault; }
+		let tmpWanted = tmpListName.toLowerCase();
+		let tmpMiss = (tmpDefault === null) ? ('{~WordListEntry:' + tmpListName + '~}') : tmpDefault;
+
+		let tmpEntries = null;
+		let tmpRandom = null;
+
+		// 1. Lists riding in the parse data (a generation run).
+		if (pRecord && pRecord.__PromptEditorWordLists && pRecord.__PromptEditorWordLists[tmpWanted])
+		{
+			tmpEntries = pRecord.__PromptEditorWordLists[tmpWanted];
+		}
+		if (pRecord && typeof pRecord.__PromptEditorRandom === 'function')
+		{
+			tmpRandom = pRecord.__PromptEditorRandom;
+		}
+
+		// 2. The pict-level resolver registry (mounted sections, host overrides).
+		if (!tmpEntries && this.pict && Array.isArray(this.pict.__PictSectionPromptEditorResolvers))
+		{
+			for (let i = 0; i < this.pict.__PictSectionPromptEditorResolvers.length; i++)
+			{
+				let tmpResolved = null;
+				try { tmpResolved = this.pict.__PictSectionPromptEditorResolvers[i](tmpWanted); }
+				catch (pError) { tmpResolved = null; }
+				if (tmpResolved && tmpResolved.length) { tmpEntries = tmpResolved; break; }
+			}
+		}
+
+		if (!tmpEntries || !tmpEntries.length)
+		{
+			return tmpMiss;
+		}
+
+		let tmpWord = weightedPick(tmpEntries, tmpRandom);
+		return (tmpWord === null) ? tmpMiss : tmpWord;
+	}
+}
+
+module.exports = PictTemplateWordListEntry;
+module.exports.template_hash = 'WordListEntry';
+module.exports.weightedPick = weightedPick;

package/source/types/PromptEditor-DefaultTypes.js

@@ -0,0 +1,116 @@
+'use strict';
+
+/**
+ * Built-in prompt types.
+ *
+ * A prompt type is a named arrangement of segments. Each segment:
+ *
+ *   {
+ *     Key:      stable identifier; a prompt's Segments object is keyed by this
+ *     Name:     the heading the compiler writes (## Name)
+ *     Guidance: one line shown to the author about what belongs here
+ *     Fixed:    true for locked text (a team preamble); Body below is used and
+ *               the section renders it read-only instead of an editor
+ *     Body:     the fixed text (only read when Fixed is true)
+ *     Optional: empty optional segments are skipped at compile time; empty
+ *               required segments compile with a placeholder note
+ *   }
+ *
+ * These cover the common shapes of working with an AI pair. They are defaults,
+ * not a registry: pass your own array as the PromptTypes option and it replaces
+ * this set entirely. To extend instead of replace, spread DefaultPromptTypes
+ * into your own array.
+ */
+
+const DefaultPromptTypes =
+[
+	{
+		Key: 'feature-request',
+		Name: 'Feature Request',
+		Description: 'Ask for a new capability: what exists, what you want, and how you will know it worked.',
+		Segments:
+		[
+			{ Key: 'context', Name: 'Context', Guidance: 'What exists today, where it lives, and anything the reader needs to know cold.' },
+			{ Key: 'request', Name: 'Request', Guidance: 'The capability you want, stated plainly.' },
+			{ Key: 'success-criteria', Name: 'Success Criteria', Guidance: 'Observable outcomes that prove it works.' }
+		]
+	},
+	{
+		Key: 'bug-report',
+		Name: 'Bug Report',
+		Description: 'Report something broken with enough signal to reproduce and fix it.',
+		Segments:
+		[
+			{ Key: 'context', Name: 'Context', Guidance: 'The system, version, and environment where the problem shows.' },
+			{ Key: 'observed', Name: 'Observed Behavior', Guidance: 'What actually happens, including exact errors.' },
+			{ Key: 'expected', Name: 'Expected Behavior', Guidance: 'What should happen instead.' },
+			{ Key: 'reproduction', Name: 'Reproduction', Guidance: 'Steps that make it happen, numbered.', Optional: true }
+		]
+	},
+	{
+		Key: 'research',
+		Name: 'Research',
+		Description: 'Send the AI to learn something and come back with a usable answer.',
+		Segments:
+		[
+			{ Key: 'context', Name: 'Context', Guidance: 'Why you are asking and what you already know.' },
+			{ Key: 'question', Name: 'Question', Guidance: 'The question, sharp enough to answer.' },
+			{ Key: 'constraints', Name: 'Constraints', Guidance: 'Boundaries: scope, sources, time period, format.', Optional: true },
+			{ Key: 'deliverable', Name: 'Deliverable', Guidance: 'The shape of the answer you want back.' }
+		]
+	},
+	{
+		Key: 'code-review',
+		Name: 'Code Review',
+		Description: 'Ask for a review with the focus stated up front.',
+		Segments:
+		[
+			{ Key: 'context', Name: 'Context', Guidance: 'What the change does and why it exists.' },
+			{ Key: 'focus', Name: 'Focus', Guidance: 'What kind of problems matter most here.' },
+			{ Key: 'out-of-scope', Name: 'Out of Scope', Guidance: 'What not to spend attention on.', Optional: true }
+		]
+	},
+	{
+		Key: 'freeform',
+		Name: 'Freeform',
+		Description: 'One open segment, no structure imposed.',
+		Segments:
+		[
+			{ Key: 'body', Name: 'Prompt', Guidance: 'Anything goes.' }
+		]
+	}
+];
+
+/**
+ * Resolve the effective prompt type set from the view options: a provided
+ * array wins outright; null/undefined means the defaults.
+ * @param {Array|null} pConfigured
+ * @returns {Array}
+ */
+function resolvePromptTypes(pConfigured)
+{
+	if (Array.isArray(pConfigured) && pConfigured.length) { return pConfigured; }
+	return DefaultPromptTypes;
+}
+
+/**
+ * Find a type by Key within a resolved set, with a freeform-style fallback so
+ * a prompt whose type was removed by the host still renders and compiles.
+ * @param {Array} pTypes
+ * @param {string} pTypeKey
+ * @returns {object}
+ */
+function getPromptType(pTypes, pTypeKey)
+{
+	let tmpFound = (pTypes || []).find((pType) => pType.Key === pTypeKey);
+	if (tmpFound) { return tmpFound; }
+	return (
+	{
+		Key: pTypeKey || 'unknown',
+		Name: (pTypeKey ? pTypeKey : 'Unknown type'),
+		Description: 'This prompt type is not in the configured set; editing the raw segments.',
+		Segments: [{ Key: 'body', Name: 'Prompt', Guidance: 'Anything goes.' }]
+	});
+}
+
+module.exports = { DefaultPromptTypes, resolvePromptTypes, getPromptType };